Ankorstore Public API (1.0.0)

Download OpenAPI specification:

The Ankorstore API enables brands and their partners to programmatically manage their presence on the Ankorstore wholesale marketplace. Through the API you can manage your product catalog and stock, process orders, handle shipping and fulfillment, and receive real-time event notifications via webhooks.

Support

For API support, contact us at api@ankorstore.com.

Getting Started

ℹ️ This guide walks you through the essential steps to make your first API call and understand the basic integration flow.

Step 1: Create an Application

To access the API you need a client_id and client_secret. Generate these by logging in at ankorstore.com and creating a new application in the Integrations area of your account.

We recommend starting with the sandbox environment to develop and test your integration before going live. See the Testing API section for details on how to get a sandbox account.

Step 2: Authenticate

The API uses OAuth2 Client Credentials. Exchange your credentials for an access token:

[POST] https://www.ankorstore.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=*

You receive a Bearer token valid for 1 hour:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Include it in all subsequent requests:

Authorization: Bearer {access_token}
Accept: application/vnd.api+json

See Authentication for rate limits and troubleshooting.

Step 3: Verify Your Connection

Confirm your token works by fetching your user configuration:

[GET] /api/v1/me/config

A successful 200 response means you are authenticated and ready to go.

Step 4: Explore the API

What you do next depends on your integration goal. Here are the most common starting points:

Sync your catalog

Fetch your products and their variants:

[GET] /api/v1/products
[GET] /api/v1/products/{product}?include=productVariants

Update stock for a product variant:

[PATCH] /api/v1/product-variants/{productVariant}/stock

For bulk product operations (import, update, delete), see Catalog Integrations.

Process orders

List your orders via Master Orders, including the underlying order details:

[GET] /api/v1/master-orders?include=internalOrder,externalOrder

Accept a new order and manage the shipping flow:

[POST] /api/v1/orders/{order}/-actions/transition

See Ordering for the full order lifecycle and status transitions.

Set up webhooks

Rather than polling for new orders, subscribe to real-time notifications:

[POST] /api/v1/webhook-subscriptions

See Webhook Subscription for available events and signature verification.

Next Steps

How to work with API

ℹ️ This section provides an overview of the general concepts and conventions used throughout the API. Also, you can find some best practices and recommendations with examples, which will help you to get started with the API.

API Specification/Schema

This API follows the Ankorstore API Specification which is based on the JSON:API specification. Please give our specification a thorough read to understand how our request and response formats work.

Interacting with API

It is recommended that you only use the resource list endpoint to retrieve newly created resource or to get the status of top level information (e.g. such as new orders or if you have been paid yet). Please use the single resource retrieval endpoint if you wish to fetch more information about each resource.

Headers

When making any request apart from retrieving an access token, the header Accept: application/vnd.api+json is required. When sending JSON within the body of a request the header Content-Type: application/vnd.api+json is also required.

🔗 Learn more about JSON:API media types

Resource Data

In every response, the actual resource data can be found in the root level object data, this will either be an array or an object, depending on if its list based or not.

🔗 Learn more about JSON:API document structure

Includes

Resources may have the ability to include data from other relations in the same request. For example, when fetching a single order you may include the retailer, the order's order items etc.

?include=retailer,orderItems.productOption.product

Includes also support nested relationships, so you can pull every order items specific product variant and base product etc.

Making non-GET requests

Includes are not just limited to GET requests, you may pass in these parameters for any other http method as well.

🔗 Learn more about JSON:API includes

Pagination

Ankorstore uses cursor based pagination. In the root level object for pagination supported endpoints you will find a meta object containing pagination information:

  type: object
  description: Meta
  properties:
    meta:
      type: object
      description: Meta with Pagination Details
      properties:
        page:
          description: Cursor pagination details
          type: object
          properties:
            from:
              type: string
            to:
              type: string
            hasMore:
              type: boolean
            perPage:
              type: integer

As an example:

{
  "meta": {
    "page": {
      "from": "63e9bacd-0288-4cf1-81ab-b34270c7f68a",
      "to": "747a1dcd-decc-4f8d-a9a9-61ff4d33d92e",
      "hasMore": true,
      "perPage": 15
    }
  }
}

You may manually construct the pagination query parameters yourself using page[limit] with page[before] or page[after] depending on which direction you wish to iterate over.

Effective pagination

We recommend using the provided helper pagination links below instead of manually constructing the URLs yourself.

The response will also provide pagination links, so you do not need to construct these yourself:

  type: object
  description: Links
  properties:
    links:
      description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction.
      type: object
      properties:
        first:
          type: string
          format: url
        next:
          type: string
          format: url
        prev:
          type: string
          format: url

As an example:

{
  "links": {
    "first": "https://www.ankorstore.com/api/v1/orders?include=&page%5Blimit%5D=15",
    "next": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bafter%5D=1189606a-139e-4b4e-917c-b0c992498bad&page%5Blimit%5D=15",
    "prev": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bbefore%5D=e04e17bb-9e70-4ecd-a8f5-4417d45b872c&page%5Blimit%5D=15"
  }
}

🔗 Learn more about JSON:API pagination

Filters

An endpoint that supports filters requires each listed filter to be wrapped in a filter object. E.g. you may wish to only retrieve new orders:

?filter[status]=ankor_confirmed

You may also chain filters as well:

?filter[status]=ankor_confirmed&filter[retailer]=1189606a-572e-4b4e-88da-b0c992498bad

What filters can be used?

The supported filters will be listed against each endpoint in the API documentation.

🔗 Learn more about JSON:API filters

API Versioning

The Ankorstore API uses URL-based versioning. The current version is v1, reflected in all endpoint paths (e.g., /api/v1/products).

Backward compatibility guarantees:

Within a major version, you can rely on the following:

  • Existing endpoints remain available at the same paths
  • Existing response fields continue to be returned with the same types
  • Existing request parameters continue to be accepted
  • Existing enum values are not removed

What may change without a new version:

  • New optional fields added to response objects
  • New optional query parameters or filter options
  • New enum values added to existing fields
  • New endpoints added under the same version prefix
  • New webhook event types

Your integration should handle these additive changes gracefully. For example, use lenient JSON parsing that ignores unknown fields rather than failing on them.

Breaking changes:

If we need to make a breaking change (removing a field, changing a type, removing an endpoint), we follow this process:

  1. The affected endpoint or field is marked as deprecated in the API documentation
  2. A migration guide is published in the Changelog describing the change and the recommended alternative
  3. Deprecated features remain functional for a transition period before removal
  4. Removal is announced in advance via the changelog

Subscribe to changelog updates and monitor deprecation notices in the API documentation to stay ahead of any changes.

Authentication

ℹ️ The Ankorstore API uses OAuth2 authentication, in order to get a client_id and a client_secret please, login at https://www.ankorstore.com/ and generate a new application in the integrations area of your account.

Testing Environment

We recommend using the testing environment to start off with, you can find more information about it in the Testing API section.

To generate a token pass in your client_id and client_secret:

{
  "method": "post",
  "headers": {
    "accept": "application/json",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "baseUrl": "https://www.ankorstore.com",
  "url": "/oauth/token",
  "body": "grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=*"
}

Failing to authenticate with Postman?

Please enable the setting Follow Authorization Header

Postman Follow Authorization Header Setting

You will receive an access_token:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>"
}

This access token has an expiry, in which you will receive an 401 Unauthenticated response. To generate a new one you can re-call the /oauth/token endpoint described above.

To authenticate with every other endpoint pass in the header Authorization: Bearer {token}. You can test if your token is working with this endpoint (this is a not a JSON:API based endpoint):

{
  "method": "get",
  "headers": {
    "accept": "application/json",
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>"
  },
  "baseUrl": "https://www.ankorstore.com",
  "url": "/api/v1/me"
}

If successful you will receive a 200 response:

{
  "data": {
    "type": "user",
    "id": 1234,
    "email": "api@ankorstore.com",
    "first_name": "Test",
    "last_name": "Account",
    "created_at": "2020-01-28T11:26:35+00:00",
    "updated_at": "2022-03-15T15:23:09+00:00"
  }
}

Rate Limiting

When authenticated (passing a valid bearer token), the rate limits are:

  • 600 requests per minute
  • 24000 per hour
  • 288000 per day

Meaning you could make a consistent 200 requests per minute, every minute, all day.

Or you could burst at up to 600 requests per minute for 40 minutes of an hour, for 12 hours of a day.

When unauthenticated for endpoints that do not require authentication the rates are:

  • 120 requests per minute
  • 4800 requests per hour
  • 57600 requests per day

Api responses have the following headers to help you track and manage the rate limits:

  • X-RateLimit-Remaining: The number of request remaining before encountering a 429 Too Many Requests error.
  • X-RateLimit-Limit: The number of requests allowed by the current window.

If you exceed these rate limits then an error status code of 429 Too Many Requests will be returned, you will also receive the following headers:

  • Retry-After: The number of seconds before more attempts become available, and you could try again.
  • X-RateLimit-Reset: A timestamp for when more attempts become available, and you could try again, specified as seconds-since-epoch.

The special exception to these limits the authentication endpoint /oauth/token which is limited to 60 requests per hour. You should not need to authenticate more than this, if you do please get in contact with us.

Token Refresh Strategy

Access tokens expire after 3600 seconds (1 hour). To maintain uninterrupted API access, implement a proactive token refresh strategy:

Recommended approach:

  1. Store the token expiry time — When you receive an access token, calculate the expiry timestamp using expires_in and store it alongside the token.
  2. Refresh before expiry — Request a new token 5–10 minutes before the current token expires, rather than waiting for a 401 response. This prevents downtime in long-running integrations.
  3. Handle 401 gracefully — If you do receive a 401 Unauthorized, immediately request a new token and retry the failed request once. Do not retry multiple times without re-authenticating.

Example token refresh logic (pseudocode):

let accessToken = null;
let tokenExpiresAt = null;

async function getToken() {
  const now = Date.now() / 1000; // Current Unix timestamp

  // If token is still valid for at least 5 minutes, reuse it
  if (accessToken && tokenExpiresAt && tokenExpiresAt - now > 300) {
    return accessToken;
  }

  // Otherwise, fetch a new token
  const response = await fetch('https://www.ankorstore.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: 'grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=*'
  });

  const data = await response.json();
  accessToken = data.access_token;
  tokenExpiresAt = now + data.expires_in;

  return accessToken;
}

Avoid: Do not request a new token for every API call. This wastes resources and will quickly hit the /oauth/token rate limit of 60 requests per hour.

Security Best Practices

Protect your credentials:

  • Never commit credentials to version control — Use environment variables or a secrets manager to store client_id and client_secret. Do not hardcode them in your source code.
  • Rotate credentials regularly — Periodically generate new API credentials in the integrations area and phase out old ones.
  • Restrict access — Only grant API credentials to systems and team members that need them. Treat client_secret with the same care as a password.

Secure token storage:

  • Store tokens in memory — For server-side integrations, keep the access token in memory rather than persisting it to disk or a database. Tokens expire after 1 hour, so there is little value in long-term storage.
  • Do not expose tokens to clients — Never send access tokens to browsers or mobile apps. API credentials are intended for server-to-server communication only.

Use HTTPS:

  • All API requests must use HTTPS. The Ankorstore API will reject requests made over unencrypted HTTP.
  • Ensure your webhook endpoint also uses HTTPS and a valid TLS certificate. See Webhook Subscription for signature verification requirements.

Monitor for anomalies:

  • Log all API authentication attempts and monitor for unexpected patterns (e.g., sudden spikes in 401 responses or token refresh requests).
  • If you suspect your credentials have been compromised, immediately revoke them in the integrations area and generate new ones.

Available APIs

ℹ️ The Ankorstore platform exposes several APIs. This page provides an overview of all available API groups and their capabilities.

Ankorstore Public API

The core API for managing your brand on the Ankorstore marketplace.

API Group Audience Description
General All Platform configuration and currency exchange rates
User All User and platform configuration (currency, country, CDN)
Catalog Brands Manage products, product variants, stock levels, and pricing
Catalog Integrations Brands Batch product import, update, and delete operations
Ordering Brands Manage master orders, internal orders, and external orders
Shipping Brands Get shipping quotes, confirm quotes, and schedule pickups
Fulfillment Brands Track fulfillments, manage replenishments, check fulfillable stock, and estimate costs
OrderPay Brands Create and manage orders for your own customers with integrated payment processing
Webhooks All Subscribe to real-time event notifications for orders, shipments, and more
Testing All Generate test orders and data in the sandbox environment

Ankorstore Stock Tracking and Logistics API (ASTRAL)

A dedicated API for advanced stock and inventory management. ASTRAL provides detailed stock visibility that goes beyond the core Catalog stock endpoints.

API Group Description
State Query current stock quantities by product variant, location, and status (available, reserved, onHand)
Movements View stock movement history — postings (individual movements) and transactions (grouped movements with context)
Locations List available stock locations (warehouses, brand locations)

ASTRAL is useful when you need to:

  • Track stock across multiple locations (your own warehouse and Ankorstore fulfillment centers)
  • Audit stock movements and understand what caused changes (orders, replenishments, adjustments)
  • Monitor lot-level inventory with expiry and sell-by dates

Integration Scenarios

ℹ️ This section describes common integration scenarios and the recommended API endpoints for each.

Catalog Synchronization (ERP / PIM)

Sync your product catalog and stock levels between your internal systems and Ankorstore.

  1. Initial catalog import — Use Catalog Integrations to batch-import products via the operations API. This handles create, update, and delete in bulk with async processing and callback notifications.
  2. Ongoing stock sync — Keep stock levels in sync by updating product variant stock via PATCH /api/v1/product-variants/{productVariant}/stock whenever your inventory changes. For detailed stock visibility across locations, use the ASTRAL Stock State endpoint.
  3. Price updates — Update product variant prices via PATCH /api/v1/product-variants/{productVariant}/prices.

Key endpoints

Endpoint Purpose
POST /api/v1/catalog/integrations/operations Create batch product operations
PATCH /api/v1/product-variants/{id}/stock Update stock for a single variant
PATCH /api/v1/product-variants/{id}/prices Update prices for a single variant
GET /api/v1/products List your products

Order Management (ERP / OMS)

Integrate order processing with your order management system.

  1. Receive new orders — Subscribe to the order.brand_confirmed webhook event to receive instant notifications when new orders arrive, instead of polling.
  2. Fetch order details — Retrieve the full order with GET /api/v1/master-orders/{id}?include=internalOrder to get all order lines, amounts, and shipping address.
  3. Process the order — Transition the order through its lifecycle: confirm, ship, and track via the order and shipping endpoints.
  4. Sync back to your systems — Use the order reference and masterOrderId fields to match Ankorstore orders with records in your OMS.

Key endpoints

Endpoint Purpose
GET /api/v1/master-orders List all orders with pagination
GET /api/v1/master-orders/{id} Get a single order with includes
POST /api/v1/orders/{order}/-actions/transition Accept/reject an order
POST /api/v1/orders/{order}/shipping-quotes Get shipping quotes
POST /api/v1/shipping-quotes/{quote}/confirm Confirm a shipping quote
POST /api/v1/webhook-subscriptions Subscribe to order events

Order event webhooks

Event When it fires
order.brand_confirmed A new order is confirmed and ready for processing
order.shipped The order has been shipped
order.received The retailer has confirmed receipt
order.brand_paid Payment has been transferred to the brand
order.cancelled The order has been cancelled

Fulfillment Center Integration

Manage inventory at Ankorstore Fulfillment Centers and track fulfillments.

  1. Send inventory — Create replenishments via POST /api/v1/fulfillment/replenishments to declare incoming stock, then update the status to confirmed when ready.
  2. Monitor stock — Check fulfillable stock with GET /api/v1/fulfillment/fulfillable and lot-level inventory with GET /api/v1/fulfillment/lots. For detailed multi-location stock data, use the ASTRAL API.
  3. Track fulfillments — When orders are fulfilled, track their progress via GET /api/v1/fulfillment/orders/{id}?include=statusUpdates.
  4. Estimate costs — Before committing to fulfillment, get cost estimates via POST /api/v1/fulfillment/costs/order.

Key endpoints

Endpoint Purpose
POST /api/v1/fulfillment/replenishments Declare incoming stock
GET /api/v1/fulfillment/fulfillable Check stock availability
GET /api/v1/fulfillment/lots List lot inventory
GET /api/v1/fulfillment/orders/{id} Track a fulfillment
POST /api/v1/fulfillment/costs/order Estimate fulfillment costs

Shipping Integration

Manage shipping for orders you ship yourself (non-fulfillment).

  1. Get quotes — When an order is ready to ship, request quotes via POST /api/v1/orders/{order}/shipping-quotes with parcel dimensions and weight.
  2. Confirm a quote — Select the best quote and confirm it via POST /api/v1/shipping-quotes/{quote}/confirm. This generates a shipping label if using Ankorstore's label service.
  3. Schedule pickup — For Ankorstore Label shipments, schedule a carrier pickup via POST /api/v1/orders/{order}/ship/schedule-pickup.

See Shipping for the full shipping flow including sequence diagrams.

Webhook-Driven Architecture

For the most responsive integration, build around webhooks rather than polling.

  1. Create an application — Your webhook subscriptions are tied to an OAuth application. List yours at GET /api/v1/applications.
  2. Subscribe to events — Create a subscription with the events you care about:
    POST /api/v1/webhook-subscriptions
    
  3. Verify signatures — Every webhook delivery includes an X-Ankorstore-Hmac-SHA256 header. Verify it using your application's signing secret. See Webhook Subscription for verification code examples.
  4. Handle retries — Failed webhook deliveries are retried automatically. Design your endpoint to be idempotent.

Available events

See the Webhook Subscription page for the full list of available events and their payload structures.

Catalog Synchronization (ERP / PIM)

Sync your product catalog and stock levels between your internal systems and Ankorstore.

  1. Initial catalog import — Use Catalog Integrations to batch-import products via the operations API. This handles create, update, and delete in bulk with async processing and callback notifications.
  2. Ongoing stock sync — Keep stock levels in sync by updating product variant stock via PATCH /api/v1/product-variants/{productVariant}/stock whenever your inventory changes. For detailed stock visibility across locations, use the ASTRAL Stock State endpoint.
  3. Price updates — Update product variant prices via PATCH /api/v1/product-variants/{productVariant}/prices.

Key endpoints

Endpoint Purpose
POST /api/v1/catalog/integrations/operations Create batch product operations
PATCH /api/v1/product-variants/{id}/stock Update stock for a single variant
PATCH /api/v1/product-variants/{id}/prices Update prices for a single variant
GET /api/v1/products List your products

Order Management (ERP / OMS)

Integrate order processing with your order management system.

  1. Receive new orders — Subscribe to the order.brand_confirmed webhook event to receive instant notifications when new orders arrive, instead of polling.
  2. Fetch order details — Retrieve the full order with GET /api/v1/master-orders/{id}?include=internalOrder to get all order lines, amounts, and shipping address.
  3. Process the order — Transition the order through its lifecycle: confirm, ship, and track via the order and shipping endpoints.
  4. Sync back to your systems — Use the order reference and masterOrderId fields to match Ankorstore orders with records in your OMS.

Key endpoints

Endpoint Purpose
GET /api/v1/master-orders List all orders with pagination
GET /api/v1/master-orders/{id} Get a single order with includes
POST /api/v1/orders/{order}/-actions/transition Accept/reject an order
POST /api/v1/orders/{order}/shipping-quotes Get shipping quotes
POST /api/v1/shipping-quotes/{quote}/confirm Confirm a shipping quote
POST /api/v1/webhook-subscriptions Subscribe to order events

Order event webhooks

Event When it fires
order.brand_confirmed A new order is confirmed and ready for processing
order.shipped The order has been shipped
order.received The retailer has confirmed receipt
order.brand_paid Payment has been transferred to the brand
order.cancelled The order has been cancelled

Fulfillment Center Integration

Manage inventory at Ankorstore Fulfillment Centers and track fulfillments.

  1. Send inventory — Create replenishments via POST /api/v1/fulfillment/replenishments to declare incoming stock, then update the status to confirmed when ready.
  2. Monitor stock — Check fulfillable stock with GET /api/v1/fulfillment/fulfillable and lot-level inventory with GET /api/v1/fulfillment/lots. For detailed multi-location stock data, use the ASTRAL API.
  3. Track fulfillments — When orders are fulfilled, track their progress via GET /api/v1/fulfillment/orders/{id}?include=statusUpdates.
  4. Estimate costs — Before committing to fulfillment, get cost estimates via POST /api/v1/fulfillment/costs/order.

Key endpoints

Endpoint Purpose
POST /api/v1/fulfillment/replenishments Declare incoming stock
GET /api/v1/fulfillment/fulfillable Check stock availability
GET /api/v1/fulfillment/lots List lot inventory
GET /api/v1/fulfillment/orders/{id} Track a fulfillment
POST /api/v1/fulfillment/costs/order Estimate fulfillment costs

Shipping Integration

Manage shipping for orders you ship yourself (non-fulfillment).

  1. Get quotes — When an order is ready to ship, request quotes via POST /api/v1/orders/{order}/shipping-quotes with parcel dimensions and weight.
  2. Confirm a quote — Select the best quote and confirm it via POST /api/v1/shipping-quotes/{quote}/confirm. This generates a shipping label if using Ankorstore's label service.
  3. Schedule pickup — For Ankorstore Label shipments, schedule a carrier pickup via POST /api/v1/orders/{order}/ship/schedule-pickup.

See Shipping for the full shipping flow including sequence diagrams.

Webhook-Driven Architecture

For the most responsive integration, build around webhooks rather than polling.

  1. Create an application — Your webhook subscriptions are tied to an OAuth application. List yours at GET /api/v1/applications.
  2. Subscribe to events — Create a subscription with the events you care about:
    POST /api/v1/webhook-subscriptions
    
  3. Verify signatures — Every webhook delivery includes an X-Ankorstore-Hmac-SHA256 header. Verify it using your application's signing secret. See Webhook Subscription for verification code examples.
  4. Handle retries — Failed webhook deliveries are retried automatically. Design your endpoint to be idempotent.

Available events

See the Webhook Subscription page for the full list of available events and their payload structures.

Webhook Subscription

ℹ️ Ankorstore provides a mechanism of webhook notifications to notify you of events that happen on the platform.

Subscribing

There are two ways to manage your webhook subscription on the platform:

  1. Via UI in your Ankorstore account. You can find this functionality in the Private Apps tab of the Integrations section.
  2. Directly via API. Find more details in the dedicated Webhoooks section of API specification.

Format

The webhook payload sent is the same as the resource object provided by the API. For example, if an order.* webhook is fired the resource will be OrderResource.

The only difference is that within the top level meta object you will receive an event object with details of the webhook which will look like this:

POST https://your-webhook-url.com/webhooks/handle

{
  "meta": {
    "event": {
      "id": "1ecdb3d8-4cc7-64b0-81e2-0242ac140007",
      "applicationId": "1ecd6935-c442-6b2c-a36b-0242ac120008",
      "type": "order.brand_accepted",
      "timestamp": 1653381780
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "data": {}
}

Events

Our currently supported events are:

  • order.brand_created - A new order is created for the brand
  • order.brand_accepted - Brand accepts the order
  • order.brand_rejected - Brand rejects the order
  • order.billing_address_updated - Billing address is updated
  • order.shipping_address_updated - Shipping address is updated
  • order.shipping_labels_generated - When shipping with Ankorstore
  • order.shipped - Fired by either shipping with custom or with Ankorstore
  • order.shipment_received - Retailer confirms reception of the order
  • order.shipment_refused - Retailer refuses the order
  • order.brand_paid - Ankorstore pays the brand for the order
  • order.cancelled - Order is cancelled
  • order.brand_accepted_reverted - Reverted Brand accepting the order
  • order.shipping_labels_generated_reverted - Reverted shipment labels generation, when shipping with Ankorstore
  • external_order.created - A new external order is created for the brand
  • external_order.awaiting_fulfillment - Order is waiting for fulfillment
  • external_order.cancelled - Order is cancelled
  • external_order.shipped - Order shipped from the warehouse
  • external_order.arrived - Order is arrived and completed

Note: When External Order is created webhook external_order.created is fired and at same time fulfillment is requested which means external_order.awaiting_fulfillment is also fired. Due to async nature of webhook when you receive these webhooks most likely order status is awaiting_fulfillment for external_order.created webhook too.

Signature

Our webhooks provide a signature so you can verify the payload hasn't been tampered with. This signature can be found on the header signature.

This is how the signature is calculated:

/**
 * @var string $payload JSON payload of the received webhook
 * @var string $secret Secret key which can be found in the particular webhook subscription settings
 * @var string $signature Calculated signature, to be compared with the value in the request header
 */
$signature = hash_hmac('sha256', $payload, $secret);

Here is the same verification in Node.js:

const crypto = require('crypto');

/**
 * @param {string} payload - Raw JSON body of the received webhook
 * @param {string} secret - Secret key from your webhook subscription settings
 * @param {string} headerSignature - Value of the "signature" request header
 * @returns {boolean} Whether the signature is valid
 */
function verifyWebhookSignature(payload, secret, headerSignature) {
  const calculated = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculated),
    Buffer.from(headerSignature)
  );
}

And in Python:

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, secret: str, header_signature: str) -> bool:
    """
    :param payload: Raw JSON body of the received webhook (bytes)
    :param secret: Secret key from your webhook subscription settings
    :param header_signature: Value of the "signature" request header
    :return: Whether the signature is valid
    """
    calculated = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(calculated, header_signature)

Use constant-time comparison

Always use a constant-time comparison function (e.g., crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python) to prevent timing attacks. Do not use === or == for signature verification.

You can calculate the webhook's signature and compare it to the one present in the request header.

Note: the secret key needed for verification webhook signature is not the same as the API secret key. Each webhook subscription has its own secret key which can be found in the particular webhook subscription settings.

Retries

If the response status code is not a 2xx then we will retry the webhook for 5 attempts with an exponential backoff.

Error Handling

ℹ️ This guide explains how the Ankorstore API communicates errors and how to handle them in your integration.

Error Response Format

The API follows the JSON:API error specification. Every error response contains an errors array with one or more error objects:

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The field is required.",
      "source": {
        "pointer": "data.attributes.field"
      }
    }
  ]
}

Error object fields

Field Type Description
status string HTTP status code (e.g., "422")
title string Short human-readable summary of the problem
detail string Specific explanation of what went wrong
code string Application-specific error code (e.g., ORDER_ACTION_REJECT_FAILED)
source.pointer string JSON Pointer to the field that caused the error (e.g., data.attributes.email)
meta object Additional metadata about the error when available

Multiple errors

A single response can return multiple errors in the errors array. For example, a validation request with several invalid fields returns one error object per field. Always iterate over the full array.

Common HTTP Status Codes

Client errors

Status Meaning When you see it
400 Bad Request The request is malformed or missing required parameters Invalid JSON, missing required headers
401 Unauthorized Authentication failed or token has expired Expired or missing Bearer token
403 Forbidden You do not have permission to access this resource Accessing another brand's resources
404 Not Found The requested resource does not exist Invalid resource ID or deleted resource
406 Not Acceptable The Accept header is not application/vnd.api+json Missing or incorrect Accept header
409 Conflict The action conflicts with the current resource state Trying to accept an already-shipped order
415 Unsupported Media Type The Content-Type header is not application/vnd.api+json Missing or incorrect Content-Type on POST/PATCH
422 Unprocessable Entity The request body is valid JSON but contains invalid data Validation errors on fields
429 Too Many Requests You have exceeded the rate limit See Rate Limiting

Server errors

Status Meaning What to do
500 Internal Server Error Something went wrong on our side Retry with backoff (see below)

Retry Strategy

Not all errors are retryable. Use this table to decide how to handle each category:

Status Retryable? Recommended action
400, 403, 404, 406, 415, 422 No Fix the request. These indicate a problem with your code or data.
401 Once Re-authenticate by fetching a new token, then retry the request.
409 Conditional Re-fetch the resource state and decide whether the action still applies.
429 Yes Wait for the duration specified in the Retry-After header, then retry.
500 Yes Retry with exponential backoff.

Exponential backoff

For retryable errors, use exponential backoff to avoid overloading the API:

Attempt 1: wait 1 second
Attempt 2: wait 2 seconds
Attempt 3: wait 4 seconds
Attempt 4: wait 8 seconds
Attempt 5: wait 16 seconds (max)

Add a small random jitter (e.g., 0–500 ms) to each wait time to prevent multiple clients from retrying in lockstep. Stop retrying after 5 attempts and log the failure for investigation.

Rate limit handling

When you receive a 429 Too Many Requests response, the API includes headers to help you recover:

  • Retry-After — Number of seconds to wait before your next request
  • X-RateLimit-Reset — Unix timestamp when your rate limit window resets

Always respect the Retry-After value rather than using a fixed delay.

Idempotency

Many operations in the Ankorstore API are idempotent, meaning you can safely retry them without causing unintended side effects:

  • GET requests are always safe to retry.
  • PATCH requests that set a field to a specific value (e.g., updating stock to 42) are idempotent.
  • POST requests are typically idempotent when you supply an entity UUID in the request body (e.g., data.id). If the resource with that ID already exists, the API returns the existing resource rather than creating a duplicate. This makes it safe to retry POST requests after a network failure as long as you provide the same UUID.

Safe retry pattern

  1. Generate a UUID client-side — Before creating a resource, generate a UUID and include it as data.id in your request body. If the request fails due to a network error, retry with the same UUID.
  2. Handle 409 gracefully — If you receive a 409 Conflict, the resource may have already moved to the desired state. Re-fetch it and verify.
  3. Use webhooks as source of truth — Rather than polling and retrying, subscribe to webhooks for state change confirmations. See Webhook Subscription.

Error Handling Examples

Handling a validation error (422)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The quantity must be at least 1.",
      "source": { "pointer": "data.attributes.quantity" }
    },
    {
      "status": "422",
      "title": "Unprocessable Content",
      "detail": "The sku field is required.",
      "source": { "pointer": "data.attributes.sku" }
    }
  ]
}

Use source.pointer to map each error back to the relevant field in your request.

Handling a state conflict (409)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "code": "ORDER_ACTION_REJECT_FAILED",
      "detail": "Order cannot be rejected from this state",
      "status": "409"
    }
  ]
}

The code field tells you the specific business rule that was violated. Re-fetch the order to check its current state before deciding on your next action.

Handling an expired token (401)

{
  "jsonapi": { "version": "1.0" },
  "errors": [
    {
      "detail": "Unauthorized",
      "status": "401"
    }
  ]
}

Request a new access token via POST /oauth/token and retry the original request. See Authentication for token management best practices.

Best Practices

  • Log error responses — Store the full error response body (including code, detail, and source) for debugging. Include the request method, URL, and your internal correlation ID.
  • Do not retry blindly — Check the status code before deciding whether to retry. Retrying a 422 wastes resources and never succeeds.
  • Surface actionable messages — Use the detail field to display meaningful messages to your users. Fall back to title if detail is not present.
  • Monitor 429 responses — Frequent rate limiting indicates your integration needs optimization. Consider caching responses and using webhooks instead of polling.
  • Handle unknown errors gracefully — If you encounter a status code not listed above, treat 4xx as non-retryable and 5xx as retryable with backoff.

Changelog

ℹ️ This page tracks notable changes to the Ankorstore Public API, including new features, improvements, deprecations, and breaking changes.

We recommend checking this page regularly to stay informed about API updates that may affect your integration.

2026

February 2026

Documentation improvements

  • Added Getting Started guide for first-time integrators
  • Added Integration Scenarios page with recommended patterns for catalog sync, order management, fulfillment, and shipping
  • Added Error Handling guide with retry strategies and idempotency guidance
  • Expanded Webhook Subscription with Node.js and Python signature verification examples
  • Expanded Authentication with token refresh strategy and security best practices
  • Expanded Testing API with sandbox limitations and mock server guidance
  • Added API Versioning policy to "How to work with API"
  • Expanded description pages for OrderPay, User, General, and Fulfillment API groups
  • Added response examples to Master Orders and OrderPay endpoint specs

API changes

  • Added available-apis overview describing all API groups including ASTRAL

2025

Q4 2025

  • Upgraded Redocly documentation renderer
  • Introduced Fulfillment endpoints for orders, lots, replenishments, and cost estimation

Staying up to date

For questions about specific changes or to report issues with the API, contact Ankorstore Support.

Testing API

ℹ️ This section contains some hints and examples on how to simplify and speed up API integration process by using our public sandbox environment for testing API.

To test the API you can use our public sandbox environment https://www.public.ankorstore-sandbox.com

A mock server is also available as a docker image: ankorstore/api-mock-server

docker run --rm -t -p 1080:1080 ankorstore/api-mock-server

How to get a public sandbox account?

Already live on Ankorstore?

If your Brand is already live on Ankorstore, please try logging in with your credentials on Ankorstore public sandbox. If it does not work, please contact your Ankorstore Brand Development Manager and request an account. Once the account is created, you will receive an email with the sandbox link to set up your credentials.

Not on Ankorstore yet?

In case you are not yet live with Ankorstore, please contact our Sales Team.

Using the public sandbox environment

When you test the order management flow through the API you may want to create some dummy orders to test the API integration, to do that you can create any number of test retailer accounts on the sandbox in order to create test orders for your brand. When placing an order you can pay using the test Stripe credit card credentials below:

Card Number: 4242 4242 4242 4242 Expiry: 04/42 CVV: 424

Creating test data

Our public sandbox environment provides some endpoints to more easily generate test data.

See the available endpoints here.

Sandbox Limitations

The public sandbox environment mirrors production functionality, but with some intentional differences to support safe testing:

What works the same as production:

  • All API endpoints and response formats
  • OAuth2 authentication flow
  • Webhook delivery (configure a publicly-accessible HTTPS endpoint)
  • Rate limiting (same limits as production)
  • Validation rules and business logic

Differences from production:

  • No real payments — Stripe is in test mode. Use the test card 4242 4242 4242 4242 for payments.
  • No real emails — The sandbox does not send transactional emails to protect test accounts from spam. You can inspect email content via the admin interface if needed.
  • Isolated data — Sandbox and production databases are completely separate. Data created in the sandbox does not appear in production, and vice versa.
  • Performance — The sandbox may be slower than production and has lower resource allocation. Do not use sandbox performance metrics for production capacity planning.

Feature parity:

The sandbox is updated alongside production releases, so new API features are available in both environments simultaneously. However, some internal-only features or beta functionality may not be enabled in the sandbox. If you encounter unexpected behavior, contact Ankorstore Support.

Data Reset and Cleanup

The sandbox environment is shared by all integrators, and test data accumulates over time. To maintain a clean testing environment:

Manual cleanup:

  • Delete test products, orders, and other resources via the API when you are done testing.
  • Use the DELETE endpoints where available to remove resources you created.

Requesting a data reset:

If you need a complete reset of your brand's sandbox data, contact Ankorstore Support with:

  • Your sandbox brand name or ID
  • Confirmation that you want all sandbox data deleted

This process is manual and may take 1–2 business days. Plan ahead if you need a clean slate for integration testing or demos.

Mock Server

For fully offline testing or CI/CD pipelines, use the official mock server Docker image:

docker run --rm -t -p 1080:1080 ankorstore/api-mock-server

The mock server returns static example responses for all documented endpoints. It does not persist data or enforce business logic, but it is useful for:

  • Testing your client code without network dependencies
  • Validating request and response serialization
  • Running integration tests in CI/CD without sandbox credentials

Note: The mock server uses example data from the OpenAPI specification. If endpoint examples are missing or outdated, the mock responses may not reflect real-world data. Always validate your integration against the live sandbox environment before going to production.

Fair Use Statement

Ankorstore provides access to its API (Application Programming Interface) for the purpose of enabling brands to integrate with our services to ease their workflow. We encourage the use of our API in accordance with the following fair use principles:

  1. Respect for Rate Limits: To ensure fair access for all users, we enforce rate limits on API requests. Developers are encouraged to adhere to these limits and implement appropriate strategies, such as utilising webhooks, caching, etc. to minimize unnecessary requests and reduce load on our servers.

  2. Data Integrity and Privacy: Developers must handle any data obtained through our API with care, respecting user privacy and maintaining data integrity. Any misuse or unauthorized access to user data is strictly prohibited and may result in termination of API access.

  3. Compliance with Terms of Service: All usage of our API is subject to our Terms of Service. Developers are expected to review and comply with these terms, which outline the rights and responsibilities associated with using our API.

By accessing or using our API, you agree to abide by these fair use principles and any additional terms and conditions specified in our documentation or Terms of Service. Ankorstore reserves the right to monitor API usage and take appropriate action to enforce these guidelines, including limiting or revoking access to the API for users who violate them.

For questions or concerns regarding API usage or these fair use principles, please contact Ankorstore Support.

Applications

List Applications

List existing application for the current authenticated user

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "jsonapi": {
    }
}

Brands

Get own brand details

Get own brand details

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": [
    ]
}

Get Retailer relation

Returns brand retailer relation

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
retailerId
required
string <uuid>

Ankorstore retailer UUID

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

General

ℹ️ This section contains general-purpose endpoints that are transversal to the system. These endpoints provide reference data useful across different integration scenarios.

💡 Currency Rates

The currency rates endpoint returns the latest exchange rates used by the Ankorstore platform.

⚠️ This endpoint is public and does not require authentication.

[GET] /api/v1/currencies/rates/latest

Each rate entry contains:

  • fromCurrency - The source currency code (e.g., "USD")
  • toCurrency - The target currency code (e.g., "EUR")
  • rate - The exchange rate as a decimal number
  • date - The date of the rate

This is useful when your integration needs to display prices in multiple currencies or reconcile amounts across different currency zones.

List of latest currency rates

Returns a list of the latest currency rates. This endpoint is public and does not require authentication.

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

Request Email Verification Code

Sends a verification code to the provided email address. Returns a verification token that must be used when verifying the code.

Authorizations:
ProductionOAuth2ClientCredentials
Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Verify Email Code

Verifies the code sent to the email address. The verification token from the initial request must be provided as the resource ID.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
email_verification
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The verification token received from the create email verification request

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

User

ℹ️ This section describes the API endpoints for retrieving user and platform configuration.

💡 User Configuration

The user configuration endpoints return locale and currency settings for the authenticated user. This is useful for adapting your integration to the user's preferences.

Current User

Retrieve the configuration for the currently authenticated user:

[GET] /api/v1/me/config

Returns:

  • currency - The user's preferred currency (e.g., "EUR", "GBP")
  • country - The user's country code (e.g., "FR", "DE")
  • browserId - A browser-session identifier

Specific User

You can also retrieve configuration for a specific user by UUID:

[GET] /api/v1/users/{id}/config

💡 Platform Configuration

The platform configuration endpoint returns global settings that apply to all users:

[GET] /api/v1/platform/config

Returns:

  • cdn - The CDN base URL for loading assets (e.g., product images)
  • stripePublicKey - The Stripe public key, needed if your integration handles payment flows client-side

Configuration for the current user

Returns configuration for the current user

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Configuration for the specified user

Returns configuration of the specified user

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

User ID

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Catalog

ℹ️ This section describes the API endpoints that you can use to manage your catalog resources, such as products, product variants etc.

💡 Working with Products

Here you will find information about the product resource and its sub-resources. If you need further information please refer to the API specification.

Including Product Variants

When retrieving the individual product via the API, you may pass an ?include=productVariants query parameter that will return associated product variants inside the included root level object.

Important Fields within Product Resource

If the field contains no data, it will be null.

💡 Stock Management

This API allows you to manage your product variants stock for the marketplace in both single- and bulk-operation mode. There are 2 opposite options available for the stock update requests - set an explicit product quantity or mark the corresponding product as "always in stock".

Stock statuses

Stock for the marketplace can be in one of two states. It can be available to order on the marketplace, or reserved for an order that has been submitted, but not yet shipped. Added together, these quantities make up the onHand state, which reflects the total quantity of the product variant "on hand" at your storage location(s).

⚠️ Unless specified otherwise, stockQuantity used in the following APIs refers to onHand quantity

See also Stock State for more general information about stock states used in the Stock Tracking APIs.

Example

  • 100 units of the product variant X are stock at your location (onHand).
  • 30 units of product variant X are reserved for Ankorstore orders that have not yet been shipped.
  • Then 70 units of product variant X are available to order on the marketplace.

Now consider you produce 50 more units of product variant X, and sell 27 units on another marketplace. Your input for the stock update API would be:

// 100 + 50 - 27 = 133
"stockQuantity": 123

Set product variant stock explicit quantity

To set an explicit quantity for the particular product variant, you should specify the amount in the payload. In case if the target product variant was previously marked as "always in stock", this option will be disabled and the stock will be set to given value.

Example of the payload to set a product variant stock to the given value (single-operation mode):

PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock

{
  "data": {
    "attributes": {
      "stockQuantity": 123
    }
  }
}

More details can be found in the endpoint specification

Set product variant as "always in stock"

To mark a particular product variant as "always in stock" and do not care about the stock amounts, you should include a flag isAlwaysInStock into the request payload. In case if the target product variant had explicit stock amount set previously, it will be reset.

Example of the payload to set a product variant stock to the given value (single-operation mode):

PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock

{
  "data": {
    "attributes": {
      "isAlwaysInStock": true
    }
  }
}

More details can be found in the endpoint specification

Update stocks of multiple product variants in single request (bulk-operation mode)

This API allows to update stocks of multiple product variants in single request. There is a specific endpoint which accepts up to 50 operations per request. Validation, business rules and payload of each operation is identical to the single-operation mode, described above.

Example of the payload to update stocks of multiple product variants in single request:

POST /api/v1/operations

{
  "atomic:operations": [
    {
      "op": "update",
      "data": {
        "type": "productVariants",
        "id": "1ed18988-3253-610e-8223-aa5cd9844001",
        "attributes": {
          "isAlwaysInStock": true
        }
      }
    },
    {
      "op": "update",
      "data": {
        "type": "productVariants",
        "id": "1ed18988-6651-610e-8223-aa5cd9844f96",
        "attributes": {
          "stockQuantity": 123
        }
      }
    }
  ]
}

More details can be found in the endpoint specification

List Products

Returns all products

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
page[limit]
integer <int64>

limit the amount of results returned

page[before]
string

show items before the provided ID (uuid format)

page[after]
string

show items after the provided ID (uuid format)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    },
  • "jsonapi": {
    },
  • "data": [
    ]
}

Get Product

Retrieve a specific product

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
product
required
string <uuid>
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

List Product Variants

Returns all product variants with their stock

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
filter[id][]
Array of strings <uuid> [ items <uuid > ]
Example: filter[id][]=3571bdc1-fa01-44fa-9342-d99bd1c2befa&filter[id][]=4271bdc1-fa01-44fa-9342-d99bd1c2befa

Filter by ID(s)

filter[productId][]
Array of strings <uuid> [ items <uuid > ]
Example: filter[productId][]=2291bdc1-bc01-44fa-9342-d95bd1c2befa&filter[productId][]=4271bdc1-fa11-54fa-9242-d99bd1c2befb

Filter by product ID(s)

filter[sku]
string
Example: filter[sku]=MY-SKU12,MY-SKU34

Filter by SKU(s)

filter[skuOrName]
string

Filter by SKU or name

filter[archived]
boolean

Filter by archived status (archivedAt attribute is nullable or not)

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{}

Get Product Variant

Get product variant with stock

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
productVariant
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Update Product Variant Stock

Update product variant stock

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
productVariant
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
ProductVariantStockUpdateSetStockQuantity (object) or ProductVariantStockUpdateSetIsAlwaysInStockRequest (object)

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Update wholesale and retail prices of a product variant

Update wholesale and retail prices of a product variant

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
productVariant
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Catalog Integrations

👋 Getting Started

The catalogue integration process relies on the concept of operations. An operation is a batch of records representing the products to create, update or delete. The completion state of an operation depends on the execution result for every record it contains. It means an operation might fail without necessarily stopping or marking the whole operation as failed (this particular state is defined as “Partially failed”).

  • Operations can be of type import, update or delete.
  • Only one open operation (not yet started) is allowed at a time.
  • Only one operation can be performed (started) at a time.
    • Any subsequent operation will be queued with status pending until previous one has finished processing.
    • If no previous operation is being processed, operation will start processing right away.

Operation Statuses

The status attribute represents the current state of the operation, below is a table that describes each state:

Status Description
created The operation was created and not yet started. At this stage, the operation is considered open and products can still be added to the batch.
skipped The operation is empty and was skipped (No action required). When an operation is skipped, an empty report is generated and the callback URL is called to notify operation is completed.
started The operation started and is processing.
pending Operation is waiting for its turn on the processing queue. The operation could not be started because another one was being processed.
succeeded All products were successfully processed.
failed All products failed to be processed.
partially_failed Not all products were successfully processed.

💡 Operation workflow

The complete workflow for an operation occurs in 3 stages: operation creation, operation processing and reporting. The following diagram illustrates these stages and how they are chained.

%%{init: {"flowchart": {"curve":"basis", "htmlLabels":false, "diagramPadding":24 } } }%%
graph LR

created("Operation Created")
start("Start Processing")
started("Processing\nStarted")
succeeded(Succeeded):::success
skipped("Processing Skipped"):::success
pending("Operation pending")
failed(Failed):::failure
partial(Partially Failed):::warning
report("Report\nGenerated")
notified(Callback Sent)

subgraph creating[Creating Operation]
created -- Add Products --> created
end

created -- Start Operation --> Start{?}
Start -->|"Another Operation execution in progress"| pending
Start --->|"No other Operation in progress"| start --> E{?}
E -->|"Batch.size > 0"| processing
E --->|"Batch is empty"| skipped

subgraph processing[Processing Operation]
direction LR
started --> succeeded
started --> partial
started --> failed
end

succeeded --> operationCompletedActions
partial --> operationCompletedActions
failed --> operationCompletedActions

subgraph reporting[Reporting]
report -- Notify --> notified
end

subgraph triggerNext[Trigger next pending Operation]
end

subgraph operationCompletedActions[Post-Complete Operation Actions]
reporting
triggerNext
end

pending -- Wait for previous Operation to finish execution --> start

skipped -- Generate empty report --> operationCompletedActions

classDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475f
classDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845
classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845
classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845
linkStyle default stroke:#788896,stroke-width:1px,fill:transparent

Creating an Operation

The full flow of creating a complete operation consists in two steps:

1. Create a new operation

Send a POST request to /api/v1/catalog/integrations/operations

Example request:

{
    "data": {
        "type": "catalog-integration-operation",
        "attributes": {
            "source": "shopify",
            "callbackUrl": "https://callback.url/called/after/processing",
            "operationType": "import"
        }
    }
}
  • At this point the new operation has been created and waiting to receive products data
  • Operation ID will be returned in the response payload

2. Add product data to operation

Send a POST request to /api/v1/catalog/integrations/operations/{operationId}/products

Products can be added only to operations with status created.

If operation has been started already (having any of started, pending, skipped, succeeded, partially_failed, failed, cancelled status), the request will fail with a 403 Forbidden status code.

Example request:

{
    "products": [
        {
            "id": "B006GWO5WK",
            "type": "catalog-integration-product",
            "attributes": {
                "external_id": "B006GWO5WK",
                "name": "Example product"
                // ...
            }
        }
    ]
}

You can perform as many requests as needed to append product data during this stage.

Operation Processing

In order to start processing the operation, you have to send a PATCH request to /api/v1/catalog/integrations/operations/{operationId} with the expected operation status (i.e. “started”).

If there is any other operation being executed at that time, the operation will be enqueued to be processed with the status pending and will be started as soon as it gets a free slot in the queue. Otherwise, the operation will be started right away.

Example request:

{
    "data": {
        "id": "90567710-de47-49e4-8536-aab80c1a469c",
        "type": "catalog-integration-operation",
        "attributes": {
            "status": "started"
        }
    }
}

Execution Report

When an operation completes, an execution report is generated. It provides the execution results (success or failure) for every product of the operation.

You can access this report by reading from the following endpoint.

GET /api/v1/catalog/integrations/operations/{operationId}/results

💡 Event Callbacks

Callbacks enable you to get notified when events occur in the operation process. For example, you can configure a callback to notify you when the operation is completed. The notification is sent via an HTTP request to the URL you specify in the operation settings.

Callbacks can be used to trigger automated actions in your integration.

Supported events

You can find here below the complete list of all the topics {{resource}}.{{event}} you can monitor:

Topic Trigger
catalog-integration-operation.completed An operation reaches a completed state such as Success, Failed, or Partially Failed
catalog-integration-operation.cancelled An operation was cancelled. This event is triggered when an operation processing is Skipped (i.e. the operation batch is empty and no action is required).

Event schema

A callback event is represented as a JSON object and has the following properties:

  • event — the name of the event that occurred (e.g. “completed”)
  • topic — the event category represented as a unique identifier of the event type. The topic is defined as a concatenation of the resource and event names {$.data.type}.{$.event}, e.g. “catalog-integration-operation.completed”. You might use this topic as a partition key to distribute the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously.
  • occurredAt — the date and time when the event occurred
  • data — the JSON:API resource describing the state of the entity which triggered the callback

A callback event is delivered as a POST request to your endpoint. The following payload represents the notification request that is triggered when an operation successfully completes:

{
    "event": "completed",
    "topic": "catalog-integration-operation.completed",
    "occurredAt": "2024-03-21T13:42:54+00:00",
    "data": {
        "id": "90567710-de47-49e4-8536-aab80c1a469c",
        "type": "catalog-integration-operation",
        "attributes": {
            // ...
            "status": "succeeded",
            "createdAt": "2024-03-21T13:13:03+00:00",
            "startedAt": "2024-03-21T13:19:32+00:00",
            "completedAt": "2024-03-21T13:42:54+00:00"
            // ...
        }
    }
}

Handling callbacks

The endpoint listening for callbacks has 3 seconds to respond with a 2xx (usually 200) response code, acknowledging a successful delivery. If the request times out or gets a response with a status code other than 2xx, it is considered failed.

Handling webhook failures

If a callback fails (whatever the reason) no further calls to the related endpoint are made.

Testing callback

A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that can be used to test callbacks. Simply create a URL on one of these sites, then configure your webhook to use it. These sites allow you to see the details of the request sent to them by the callback service.

In addition, the Ngrok service (https://ngrok.com) allows you to tunnel callback requests to a non-publicly accessible server, enabling you to test your callback-handling code before making it public.

Operations and Drafts behaviour

Type Behaviour
import When executing an import operation existing drafts will be cleaned and new ones will be created if any of the products attached to the operation has any validation issue.
update Will not have any impact on existing drafts.
delete Will not have any impact on existing drafts.

Create a new operation

Create new Operation to process over related Catalog Integration

ID of the operation will be returned on the response payload. This ID should be used to add products data through POST /catalog/integrations/operations/{ID}

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Callbacks

Request samples

Content type
application/vnd.api+json
Example
{}

Response samples

Content type
application/vnd.api+json
Example
{}

Callback payload samples

Callback
POST: A callback triggered when events occur in the operation process
Content type
application/json
{
  • "event": "completed",
  • "topic": "catalog-integration-operation.completed",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Create a deletion operation

Creates an Operation that deletes products from Ankorstore's catalog. The operation is started directly after creation.

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
source
required
string (OperationSource)
Enum: "shopify" "woocommerce" "prestashop" "other"

Source of the operation

callbackUrl
required
string

The url of the endpoint that will be called when an operation completes. When an operation reaches a completed state such as Success, Failed, or Partially Failed the API platform will trigger a request to your endpoint.

required
Array of objects

Responses

Callbacks

Request samples

Content type
application/vnd.api+json
{
  • "source": "shopify",
  • "products": [
    ]
}

Response samples

Content type
application/vnd.api+json
{}

Callback payload samples

Callback
POST: A callback triggered when events occur in the operation process
Content type
application/json
{
  • "event": "completed",
  • "topic": "catalog-integration-operation.completed",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Retrieve an operation

Returns specific Operation resource data

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
operationId
required
string <uuid>

The unique identifier of the operation

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
Example
{}

Patch Operation resource

Patch Operation resource

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
operationId
required
string <uuid>

The unique identifier of the operation

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
Example
{}

Add products to an operation

Add products data to an existing Operation resource

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
operationId
required
string <uuid>

The unique identifier of the operation

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
Array of objects

Responses

Request samples

Content type
application/vnd.api+json
{
  • "products": [
    ]
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "meta": {
    }
}

Retrieve an operation report

Once an operation is completed, an execution report is generated. This report summarises the result of the operation execution for each of its products.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
operationId
required
string <uuid>

The unique identifier of the operation

query Parameters
page[limit]
integer <int64>

limit the amount of results returned

page[before]
string

show items before the provided ID (uuid format)

page[after]
string

show items after the provided ID (uuid format)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    },
  • "jsonapi": {
    },
  • "data": [
    ]
}

Integration

Update status of External Integration

Allows to notify Ankorstore about changing the status of an integration of external platform

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/json
required
platform
required
string
Enum: "shopify" "woocommerce" "prestashop" "odoo" "sellsy"
status
required
string
Enum: "enabled" "disabled"

Responses

Request samples

Content type
application/json
{
  • "platform": "shopify",
  • "status": "enabled"
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Ordering

ℹ️ This section of API allows to manage different types of orders in the system. Depending on the order type, there are different endpoints available to manage them. Before starting to work with the API, it is recommended to read the documentation to better understand the differences between the order types, their workflow and lifecycle.

💡 General conceptions

  • Internal Order - A regular type of order created via Ankorstore platform. It may have different types of shipping and payment. The client of such an order is always an existing retailer entity, available in Ankorstore.
  • External Order - A special type of order created by a brand for an external customer, which might not exist in Ankorstore. This type of order does not expect retailer as a reference to the Ankorstore entity, but rather allows brand to provide a custom client details, such as address, contact information etc. The orders of this type in the current version of the platform are fulfilled by the Fulfillment Centers only and do not support any other type of shipping.
  • Master Order - Not a separate type of order, but rather a wrapper over other order types. It allows to have a single reference to the order, regardless of its type. A Master Order usually has a one-to-one relationship with either Internal Order or External Order so either of these order can be accessed via the Master Order reference.

💡 Working with Master Orders

Access different types of orders via Master Order

As mentioned above, the Master Order is a wrapper over other order types. It allows to have a single reference to the underlying order, regardless of its type. The available Master Order endpoints allow to fetch a list of available Master Orders and also get a single Master Order by its ID and, following JSON:API specification, including the underlying orders as relations. This approach allows to deal with different order types in a unified way (e.g. listing, pagination). However, it is still possible to access the underlying Internal Orders directly, in order to keep the backward compatibility.

graph LR
    A[Master Order] --> B[Internal Order]
    A --> C[External Order]

Master Order as a standalone resource might not bring much value, but the Master Order endpoints allow to include a corresponding wrapped orders as relations, which per se contain a useful payload.

Includes

The Master Order has a one-to-one relationship with either Internal Order or External Order. Hence, passing query parameter ?include=internalOrder, ?include=externalOrder or by combining different includes, (separated by comma e.g. ?include=internalOrder,externalOrder) you will receive wrapped order as a relation.

For example, let's say you have only 2 orders, one of them is Internal Order, another is External Order. If you don't include any relation into request to the List Master Orders,

[GET] /api/v1/master-orders

the response will contain only a list of identifiers without any wrapped orders:

{
  //...
  "data": [
    {
        "type": "master-orders",
        "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89",
    },
    {
        "type": "master-orders",
        "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f",
    },
    //...
  ],
  //...
}

But with the inclusion of the wrapped order relations to the same endpoint

[GET] /api/v1/master-orders?include=internalOrder,externalOrder

the result will contain included information about the actual orders:

{
  //...
  "data": [
    {
      "type": "master-orders",
      "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89",
      "relationships": {
        "internalOrder": {
          "data": {
            "type": "internal-orders",
            "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89"
          }
        },
      }
    },
    {
      "type": "master-orders",
      "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f",
      "relationships": {
        "externalOrder": {
          "data": {
            "type": "external-orders",
            "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f"
          }
        }
      }
    },
    //...
  ],
  "included": [
    {
      "type": "internal-orders",
      "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89",
      "attributes": {
        // Internal order attributes here
      }
    },
    {
      "type": "master-orders",
      "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f",
      "attributes": {
        // External order attributes here
      }
    },
    //...
  ]
  //...
}

To learn more about JSON:API include mechanism, please refer to the official docs.

💡 Working with Internal Orders

Despite the fact that the Internal Orders can be accessed via the Master Order endpoints, it is still possible to access them directly, in order to keep the backward compatibility. Moreover, some actions (e.g. transiting an Internal Order to the next state) are only available via the direct Internal Order endpoints.

Includes

For every endpoint that returns the Internal Order resource you may pass an ?include= query parameter that will return extra information inside the included root level object. The supported resources to include are retailer, billingItems, orderItems, orderItems.productVariant and orderItems.productVariant.product. Please note that, if you include orderItems.productVariant you do not need to specify orderItems separately. It will be automatically included. As an example, to include all data possible you would do ?include=retailer,billingItems,orderItems.productVariant.product

Product options usage is deprecated

Please note, that we have fully completed migrating our system to the new product model with product options replaced by product variants. It means, the usage of product options is deprecated and will be removed in the future versions of the API.

Please, consider updating your API clients in favor of using orderItems.productVariant instead of orderItems.productOption to avoid any issues in the future. For the time being, the API still supports both approaches, but we strongly encourage you to not rely on the deprecated resources anymore because we cannot fully guarantee their stability due to some technical limitations.

Important Fields within Internal Order resource

If the field contains no data, it will be null. The only exception currently to this is shippingOverview which can be viewed below. The fields listed below are not all the fields, please see the API specification for all of them.

Status status

The status field is the current state of the order, below is a table that describes each step:

Status Description
ankor_confirmed The order has been confirmed by Ankorstore and now a decision can be made whether to accept or reject this order.
rejected The order has been rejected, Ankorstore needs to approve this rejection. If it does, the status will moved to cancelled.
brand_confirmed The order has been accepted. it now needs to be shipped to the retailer.
shipping_labels_generated The order has been shipped with Ankorstore and the labels have been generated - these are now available in the order resource data within shippingOverview.
fulfillment_requested The brand has chosen to fulfill the order, or the order was automatically fulfilled. The order will remain in this state until it has been fulfilled by the fulfillment provider.
shipped The order has either been picked up by an Ankorstore carrier (e.g UPS) or the brand has chosen to ship with their own carrier.
received The retailer has received the package, if shipped with Ankorstore this is automatic from the carrier otherwise for custom shipping the retailer has to manually acknowledge this.
reception_refused The retailer has refused the reception of the package - if Ankorstore approves the reason the order will move to cancelled. The status can also move to received if the retailers issues have been resolved by the brand or Ankorstore.
invoiced The final invoice has been issued for this order.
brand_paid The brand has been paid in full for this order.
cancelled The order is cancelled.
flowchart LR
    ankor_confirmed -- accept order -->brand_confirmed
    ankor_confirmed -- reject order -->rejected-->cancelled
    brand_confirmed -- shipping method: custom -->shipped
    brand_confirmed -- shipping method: ankorstore -->shipping_labels_generated
    brand_confirmed -- shipping method: fulfillment -->fulfillment_requested
    shipping_labels_generated-->shipped
    fulfillment_requested-->shipped
    shipped-->reception_refused-->cancelled
    shipped-->received-->invoiced-->brand_paid
    reception_refused-->received

Not to be confused: Status vs Shipping Flow

The above diagram shows what status the order will be in based on the actions performed in the API. The most confusing may be the shipping flow. To reach the shipped or shipping_labels_generated status, a shipping quote must always be generated and then confirmed. Please see shipping an order for further details.

Shipping Method shippingMethod

What shipment method has been chosen for this order. Either ankorstore for using Ankorstore's shipping service, custom for using the brand's own carrier or fulfillment if the order is shipped from a fulfillment centre This field is null when no choice has yet been made.

Shipping Overview shippingOverview

Field Availability

The object shippingOverview is only available when retrieving a single order. This data is not available when retrieving a list of orders.

Submitted At submittedAt

This is the date the retailer submitted their whole order.

Shipped At shippedAt

This is when the brand shipped the order.

Brand Paid At brandPaidAt

This is when Ankorstore pays the brand, if it is null then payment is still pending.

Interacting with Internal Orders

When a brand receives a new order, it arrives in the ankor_confirmed status. The brand can then perform certain transitions using a single endpoint:

POST /api/v1/orders/{id}/-actions/transition

This endpoint will accept different payloads depending on what transition is provided. This page will detail each transition that may be performed and when.

All the implementation details and fields can be found in the endpoint documentation.

No going back!

Once an order is accepted or rejected it cannot be reversed. If this was a mistake the brand can contact Ankorstore through the normal channels to revert the order to ankor_confirmed.

If an order is rejected you need to provide a detailed reject reason. Otherwise, after the order is accepted the brand then needs to ship it. Please see shipping for further details.

Accepting an Internal Order

Can be performed when the order is in ankor_confirmed.

In order to accept an order without any item modifications a simple payload detailing the transition will suffice:

{
  "data": {
    "type": "brand-validates"
  }
}

The order will move from ankor_confirmed to brand_confirmed.

Accepting an Internal Order with modifications

Can be performed when the order is in ankor_confirmed.

Sometimes you may wish to modify the order before accepting it if for example you do not have the items in stock or further communication has taken place with the retailer.

The order items can only be modified at this stage. The rules of the payload are as follows:

  • To leave an item's quantity as is, do not include it in the payload below
  • To update an item's quantity, include it in the payload below with the new quantity (cannot be above the current quantity)
  • To remove an item entirely, set the item's quantity to 0.

You cannot remove all items, please reject the order in this scenario.

{
  "data": {
    "type": "brand-validates",
    "attributes": {
      "orderItems": [
        {
          "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89",
          "type": "order-items",
          "attributes": {
            "quantity": 12
          }
        },
        {
          "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f",
          "type": "order-items",
          "attributes": {
            "quantity": 0
          }
        }
      ]
    }
  }
}

The order will move from ankor_confirmed to brand_confirmed.

Rejecting an Internal Order

Can be performed when the order is in ankor_confirmed.

To reject an order you must provide a reason listed below for the rejectType field.

  • BRAND_ALREADY_HAS_CUSTOMER_IN_THE_AREA - Brand already has a customer in the area

  • BRAND_CANNOT_DELIVER_TO_THE_AREA - Brand cannot make a delivery to the target area

  • BRAND_HAS_EXCLUSIVE_DISTRIBUTOR_IN_THE_REGION - The brand already has an exclusive distributor in the target region

  • BUYER_NOT_A_RETAILER - The buyer does not seem to be a retailer

  • ORDER_ITEMS_PRICES_INCORRECT - The prices of items in this order were incorrect

  • PAYMENT_ISSUES_WITH_RETAILER - Brand had payment issues in the past with this retailer

  • PREPARATION_TIME_TOO_HIGH - The time needed for the order preparation is excessively high

  • PRODUCT_OUT_OF_STOCK - Order cannot be processed because one or multiple ordered products are not in the stock

  • PURCHASE_NOT_FOR_RESALE - This purchase does not seem to be for resale

  • RETAILER_AGREED_TO_DO_CHANGES_TO_ORDER - The retailer agreed so that they can do changes to the order

  • RETAILER_NOT_GOOD_FIT_FOR_BRAND - The retailer who made an order does not fit the brand's criteria

  • RETAILER_VAT_NUMBER_MISSING - The retailer VAT number is missing

  • OTHER - If no reason above is suitable you can use value, but you MUST provide a rejectReason which accepts a plain text string of 1000 characters.

Example rejection

{
  "data": {
    "type": "brand-rejects",
    "attributes": {
      "rejectType": "ORDER_ITEMS_PRICES_INCORRECT"
    }
  }
}

Example rejection with OTHER

{
  "data": {
    "type": "brand-rejects",
    "attributes": {
      "rejectType": "OTHER",
      "rejectReason": "a different reason"
    }
  }
}

The order will move from ankor_confirmed to cancelled.

Resetting an Internal Order's generated shipping labels

Can be performed when the order is in shipping_labels_generated.

To reject an order you must provide a reason listed below for the resetType field.

  • BRAND_NEED_MORE_LABELS_TO_SHIP - Brand needs more shipping labels to ship

  • BRAND_PUT_WRONG_WEIGHT_DIMENSIONS - Brand put wrong parcel weight and/or dimensions

  • BRAND_SHIPS_WITH_DIFFERENT_CARRIER - Brand wants to ship with a different carrier

  • PROBLEM_DURING_SHIPPING_LABEL_GENERATION - There was a problem during the shipping labels generation

  • RETAILER_ASKED_DELIVERY_ADDRESS_CHANGE - The retailer asked for a delivery address change

  • SHIPPING_ADDRESS_MISMATCHES_PICKUP_ADDRESS - The shipping address mismatches the pickup address

  • OTHER - If no reason above is suitable you can use this value, but you MUST provide a reason which accepts a plain text string of 300 characters maximum.

Example reset shipping labels

{
  "data": {
    "type": "brand-resets-shipping-labels-generation",
    "attributes": {
      "resetType": "BRAND_PUT_WRONG_WEIGHT_DIMENSIONS"
    }
  }
}

Example reset shipping labels with OTHER

{
  "data": {
    "type": "brand-resets-shipping-labels-generation",
    "attributes": {
      "rejectType": "OTHER",
      "reason": "a different reason"
    }
  }
}

The order will move from shipping_labels_generated to brand_confirmed.

Requesting fulfillment by Ankorstore Logistics for an Internal Order

Can be performed when the order is in brand_confirmed.

Ankorstore Logistics will fulfill the order and ship it to the retailer. The order will move from brand_confirmed to fulfillment_requested.

Must be preceded by a fulfillability check, since it requires the brand to be enrolled with Ankorstore logistics, and sufficient stock to be available in an Ankorstore warehouse.

Validation errors can include:

  • not_a_fulfillment_brand - The brand is not enrolled with Ankorstore Logistics
  • unavailable_items - One or more items are not available in the warehouse. The response will include a list of the unavailable items, which map to productVariant.fulfillableId
  • already_being_fulfilled - The order is already being fulfilled
  • not_available_for_international_orders - Fulfillment is currently not available for orders crossing a customs border
  • stock_is_being_transferred - The stock is currently being transferred between warehouses

Available operations on Internal Orders

You can also find some details about shipping in the dedicated Shipping section,

💡 Working with External Orders

The information about External Orders can be only listed and retrieved as a relation of Master Order endpoints. However, some External Order-specific operations are also available, see the section below.

How to create External Order?

The creation of External Order is as easy as just sending one request to the API. The process of creation is asynchronous, because it involves some 3rd party services, such as Fulfillment Center operators, who needs to confirm the possibility of fulfillment (availability of the stock, etc.).

For better understanding, you can treat the creation of External Order an "intent to create an order with particular items for particular client". So after submission, the intent is either accepted or rejected by API, depending on the different factors (such as availability of the stock, etc.). More on this below.

Preparing for External Order creation

Usually, before sending the actual Create External Order request, you need collect some information in order to make the request valid.

The request payload is described in details in the endpoint specification but here we will take a general look at the necessary pieces of the information required for the request:

  1. Valid set of fulfillables. The endpoint accepts the list of fulfillable items. The identifiers should be valid and the quantities should be evenly divisible by the batch size. Otherwise, the request might be rejected by the API.
  2. Valid shipping address. This is one of the most important parts of the order, please make sure the address is completely valid, the provided postal code and phone number match the specified country etc. Otherwise, any mistake in the address fields could be only fixed with the help of the Ankorstore Support team.
  3. Generate unique identifier (UUID) for the order. Despite this field is optional, considering the asynchronous nature of the process, it is highly recommended to provide it. This will allow you to immediately get the information about the order, check its status etc. Omitting this field will result in the generation of the identifier by API and will only make sense if you don't want to check the result immediately ("fire-and-forget").

The last 2 steps can be done independently, but the first step is a bit more complicated, because it requires the knowledge about the available products and their identifiers. This information can be obtained via the Catalog API and Fulfillment API.

A practical example

The assumption here is that you already authenticated and able to access the API. If not, please follow the Authentication section first.

Here is an example of the real use-case for the External Order creation. Let's say, you'd like to create an order for the following client:

Field Value
Client name John Doe
Company name ACME
Phone +33 612345678
Email john@acme.com
Address 123, Rue de Foo Bar, Paris, 75001, France

with the following content:

Product SKU Quantity
AB-1234 12
CD-00-XY 5

In this scenario, you should take the following steps:

[1] Find the fulfillable identifiers for the given products

This can be achieved by sending a request to the List Product Variants

[GET] /api/v1/product-variants?filter[sku]=AB-1234,CD-00-XY

and finding the fulfillable identifiers for the desired products.

As a result of this step, you should have the following information:

Product SKU Quantity Fulfillable ID
AB-1234 12 1ac37dbf-f25d-4c0c-bcc8-ad8af946b541
CD-00-XY 5 e5e91243-d11a-47a3-9308-22af70da5bc4

[2] Find the information about the available stocks for the products

This information can be retrieved by sending a request to List Fulfillable Endpoint. With the fulfillable identifiers from the previous step, you can send the following request:

[GET] /api/v1/fulfillment/fulfillable?fulfillableIds[]=1ac37dbf-f25d-4c0c-bcc8-ad8af946b541&=fulfillableIds[]=e5e91243-d11a-47a3-9308-22af70da5bc4

and get quantity information for the given fulfillables from the response.

For each requested fulfillable item, the response of this endpoint contains 2 properties:

  • unitQuantity - the total available quantity of the product, in minimal atomic units (e.g. bottles)
  • batchQuantity - the total available quantity of the batches (packs) of the product (e.g. boxes of bottles)

Having these 2 properties, you should check 2 things, before move on:

  1. The planned quantity for the corresponding product in the order should not exceed unitQuantity from the response. If the requested quantity is greater than the unitQuantity, the request will be rejected.
  2. The requested quantity of the product should be evenly divisible by the "batchSize", which can be calculated by dividing returned unitQuantity by the batchQuantity. This is required because the Fulfillment Center can only fulfill products by the whole batches (packs). Violating this rule will result in the rejection of the request.

After these simply calculations, you should end up with the following information:

Product SKU Quantity Fulfillable ID Batch Size
AB-1234 12 1ac37dbf-f25d-4c0c-bcc8-ad8af946b541 3
CD-00-XY 5 e5e91243-d11a-47a3-9308-22af70da5bc4 5

as you can see here, the quantities are evenly divisible by the batch sizes, which means the products information is ready to go. For instance, the products from our example will be fulfilled by 4 packs of AB-1234 and 1 pack of CD-00-XY.

[3] Validate the shipping address

The next step is to validate the shipping address. As it was mentioned before, the address properties should correspond to each other and be valid.

So the user information in this example looks valid and the only thing left is to distribute the address fields to the corresponding properties:

{
    "country": "FR", // ISO 3166-1 alpha-2 country code
    "postalCode": "75001", // Valid postal code for France
    "city": "Paris",
    "street": "123, Rue de Foo Bar", // 60 characters max, otherwise will not fit the place on the printed label
    "company": "ACME",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+33 612345678", // Valid phone number for France
    "email": "john@acme.com"
}

[4] Generate unique identifier for the order

The next step is to generate UUID (preferably UUIDv6) for the order being created. You can use any library of your choice to generate it, the only requirement is that it should follow the specification.

[5] Send the request to the API

At this point, you are ready to send the request to the API. What is left to do is to prepare API request payload by putting together all the information collected in the previous steps. For the exact payload structure, please refer to the endpoint specification.

The successful acceptance of the request does not mean 100% guarantee that the order will be fulfilled by Fulfillment Centre. The validation on the Fulfillment Centre side is usually taking some time, so you should check the status of the order by sending request to the Get Master Order endpoint, using the generated UUID as an identifier and including the externalOrder relation. The status of the included External Order will indicate the actual status of the order.

⚠️ Deprecation notice

Some of the endpoints and documents from this section are deprecated and will be removed in the future. You can temporarily still find them here.

List Master Orders

Retrieve a list of Master Orders

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
include
string
Enum: "internalOrder" "externalOrder" "shipment"
page[limit]
integer <int64>

limit the amount of results returned

page[before]
string

show items before the provided ID (uuid format)

page[after]
string

show items after the provided ID (uuid format)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
Example
{}

Get Master Order

Retrieve a specific Master Order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
master_order
required
query Parameters
include
string
Enum: "internalOrder" "externalOrder" "shipment"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
Example
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Patch Master Order

Patch a specific Master Order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
master_order
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required

Master Order update payload

required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Check whether a master order is fulfillable

Check whether a master order is fulfillable

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    }
}

Request fulfillment for a master order

Request fulfillment for a master order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    }
}

List Master Order Fulfillments Relationships

Retrieve a list of fulfillment relationships for a Master Order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    },
  • "included": [
    ]
}

List Master Order Fulfillments

Retrieve a list of fulfillments for a Master Order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

List master order shipment tracking

Retrieve shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

Create master order shipment tracking

Create shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

Update master order shipment tracking

Update shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

List Internal Orders

Retrieve a list of Internal Orders

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
filter[retailer]
string
Example: filter[retailer]=23e4567-e89b-12d3-a456-426614174000

Retailer Id

filter[status]
string
Enum: "ankor_confirmed" "rejected" "brand_confirmed" "shipping_labels_generated" "fulfillment_requested" "shipped" "reception_refused" "received" "invoiced" "brand_paid" "cancelled"
Example: filter[status]=ankor_confirmed

Order Status

page[limit]
integer <int64>

limit the amount of results returned

page[before]
string

show items before the provided ID (uuid format)

page[after]
string

show items after the provided ID (uuid format)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    },
  • "jsonapi": {
    },
  • "data": [
    ]
}

Get Internal Order

Retrieve a specific order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Check Internal Order Fulfillability

Check whether an internal order can be fulfilled by Ankorstore logistics

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    }
}

Transition Internal Order

Transition an order to a new state. This endpoint can be used to accept an order (with or without modifications), reject an order or reset generated shipping labels currently. Please see the documentation for more information.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
Brand Accepts Payload (object) or Brand Rejects Payload (object) or Brand Resets Shipping Labels Generation (object) or Brand Requests Fulfillment (object)

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Create NAFO External Order

Creates a new External Order of type nafo

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/json
required
required
object

Shipping address of the recipient.

required
Array of objects

List of fulfillable items with their corresponding quantities.

masterOrderUuid
string <uuid>

Pre-generated UUID for the order being created. Despite this UUID is optional and being omitted, will be generated by the system, having it in advance will make it easier to identify and track the status of the created order (considering the asynchronous nature of the process).

customReference
string

Optional brand-defined custom reference to add to the created order. Usually represents some order identifier in the brand's order management system, used outside of Ankorstore.

recipientType
string
Default: "business"
Enum: "business" "consumer"

The type of recipient for this order

object or null

Allow you to specify opening times for the customer.

object or null

Allow you to specify specific instructions for packing.

object or null

Allow you to specify the need of booking an appointment before delivery

invoiceUuid
string <uuid>

UUID for the invoice document (type: fulfillment-media) associated with this order. The UUID should correspond to a document previously uploaded via POST /api/fulfillment/v1/media/upload Required if the order crosses a customs border

Responses

Request samples

Content type
application/json
{
  • "shippingAddress": {
    },
  • "items": [
    ],
  • "masterOrderUuid": "8f6deb2e-3f81-488c-8887-508b733f0a5b",
  • "customReference": "string",
  • "recipientType": "business",
  • "deliverySchedule": {
    },
  • "packingInstruction": {
    },
  • "deliveryAppointment": {
    },
  • "invoiceUuid": "d7b1f0c6-56bf-43f4-8d08-5baf1e1acebc"
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    }
}

Shipping

ℹ️ Here your can find endpoints related to different types of shipping, available on the platform.

Please note, that shipping information described here is only available for Internal Orders. For more details check the Orders section.

💡 How to ship an Internal Order?

For shipping an internal order, Ankorstore provides two methods:

  • Ankorstore Label method : For this method, the shipping will be handled by Ankorstore carrier partners. The cost of shipping will be charged to the brand.
  • Brand Label method : For this method, the shipping will be handled by the brand itself and Ankorstore will provide a refund.

To retrieve the shipping quotes, the brand must call the following endpoint:

  • Get quote list : /v1/orders/:orderId/shipping-quotes

In the list of quotes, the Ankorstore Label method can be found by the carrier name ankorstore :

{
    "data": [
        {
            "quoteUuid": "1efcd179-5753-6ee0-91a4-72a6c4e49e6a",
            "carrierCode": "ankorstore",
            "serviceCode": "",
            "serviceCommercialName": "",
            "collectionMethod": [],
            "shippingCost": {
                // Amount refunded to the brand if the quote is selected
                "amount": 1006,
                "currency": "EUR"
            },
            "timeInTransit": null
        }
    ]
}

Other methods have a different carrierCode:

{
    "data": [
        {
            "quoteUuid": "1edd47df-b91a-68b0-b517-52e73cd28d4f",
            "carrierCode": "ups",
            "serviceCode": "11",
            "serviceCommercialName": "UPS Standard",
            "collectionMethod": [
                "pickup",
                "drop-off"
            ],
            "shippingCost": {
                // Amount subtracted from total amount if the quote is selected
                "amount": 807,
                "currency": "EUR"
            },
            "timeInTransit": {
                "estimatedDeliveryDate": "2025-01-10",
                "pickupDate": "2025-01-08",
                "businessDaysInTransit": 2
            }
        }
    ]
}

Once the quote is generated, the brand must confirm the selected one by calling :

  • Confirm shipping : /v1/shipping-quotes/:quoteId/confirm

To find out more about Ankorstore's shipping options, please visit our FAQs.

The brand can list many quotes before they decide to confirm the quote. An example flow:

flowchart LR
    A[Start] --> B[Get shipping quote list: 
orders/:orderId/shipping-quotes] B --> B.1{ankorstore carrier quote selected ?} B.1 -- NO --> B.YES[The brand will get the quote amount as a refund for the shipping] B.1 -- YES --> B.NO[The brand will be charged for the shipping by the quote amount] B.YES --> D[I Confirm the quote:
shipping-quotes/:quoteId/confirm] B.NO --> D

Parcels

On either shipping method, if the brand has previously generated a quote and is now generating a new one the full list of parcels must be provided. The quote endpoint cannot be called with an empty parcel list to re-use the old parcel data.

Confirming a quote

To confirm a quote, the ID must be provided when calling the /v1/shipping-quotes/:quoteId/confirm endpoint.

All information regarding shipping and tracking is stored within the shippingOverview object. This includes the latestQuote generated and the shippingCostsOverview.

💡 Shipping Costs

In the endpoint for listing quotes v1/orders/:orderId/shipping-quotes, the shipping cost of the selected quote will be the fee subtracted from total amount for carriers (ups, dhl_express, etc) and a refund amount for ankorstore carrier (amount refunded to the brand):

{
    "data": [
        {
            "quoteUuid": "1edd47df-b91a-68b0-b517-52e73cd28d4f",
            "carrierCode": "ups",
            "serviceCode": "11",
            "serviceCommercialName": "UPS Standard",
            "collectionMethod": [
                "pickup",
                "drop-off"
            ],
            "shippingCost": {
                // Amount subtracted from total amount if the quote is selected
                "amount": 807,
                "currency": "EUR"
            }
        },
        {
            "quoteUuid": "1efcd179-5753-6ee0-91a4-72a6c4e49e6a",
            "carrierCode": "ankorstore",
            "serviceCode": "",
            "serviceCommercialName": "",
            "collectionMethod": [],
            "shippingCost": {
                // Amount refunded to the brand if the quote is selected
                "amount": 1006,
                "currency": "EUR"
            }
        }
    ]
}

Want more information about shipping contribution?

To find out more about Ankorstore's contribution to your shipping costs, please visit our FAQs.

Shipping with Brand Label

The quote action will return an amount that will be refunded back to the brand based on the shipping grid refund matrix.

The confirm action is synchronous, meaning when the action is called the order resource will have its status changed to shipped upon returning a response. It is up to brand to provide tracking details for the retailer when calling this action.

sequenceDiagram
  participant O as Order
  participant SWC as Ship : orders/:orderId/shipping-quotes
  participant SC as Confirm : shipping-quotes/:quoteId/confirm
  participant SH as Shipped

  O->>SWC: List quotes
  SWC-->>O: Quote OK
  O->>SC: Confirm 'ankorstore' carrier quote
  SC->>SH: Status
  SC-->>O: OK

In the orders/:orderId/shipping-quotes endpoint response, the quote uuid generated is the following:

 {
    "quoteUuid": "1efcd179-56c1-6432-98e7-72a6c4e49e6a",
    "carrierCode": "ankorstore",
     ...
   }
 }

Shipping with Ankorstore Label (carrier name like ups, dhl_express, etc)

When calling the confirm action for the order's Ankorstore shipping quote, the returned order resource's status will still be brand_confirmed. A job in the background will generate the shipping labels for the order. It is this background processing that moves the status to shipping_labels_generated.

How will I know when the labels have been generated?

Right now, the order must be polled periodically. Checking every minute would be suitable to detect the status change and then pull the label PDF data within the shippingOverview of an order resource.

sequenceDiagram
  participant O as Order
  participant SWA as Ship with Ankorstore Label : 
orders/:orderId/shipping-quotes participant SC as Confirm shipping :
shipping-quotes/:quoteId/confirm participant BG as Async Processing participant C as Carrier participant SH as Shipped O->>SWA: Get shipping quote list SWA-->>O: I accept one quote O->>SC: I confirm the quote SC-->>O: OK status=brand_confirmed SC-->>BG: Dispatch generate labels job Note over SC,BG: Async worker job BG-->>O: Labels generated, status=shipping_labels_generated Note over BG,O: (Async worker) C-->>SH: Parcels scanned, status=shipped Note over C,SH: (External service)

At step 6 (shipping labels generated) the download URL's for each packages label will be available within the shippingOverview of an order resource. These labels are in PDF format and will also be visible in order details page on Ankorstore.

In the orders/:orderId/shipping-quotes endpoint response, the quote uuid generated is the following:

 {
    "quoteUuid": "1efcd179-56c1-6432-98e7-72a6c4e49e6a",
    "carrierCode": "ups",
     ...
   }
 }

Schedule a Pickup

If the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup for this order. A pickup can only be scheduled on a working day (monday to friday). For full information please refer to the API documentation.

Pickup is not accepted

For now, Ankorstore does not know in advance which date/time configuration is available, if the requested pickup is denied please try a different date or time frame.

⚠️ Deprecation notice

Some of the endpoints and documents from this section are deprecated and will be removed in the future. You can temporarily still find them here.

List master order shipment tracking

Retrieve shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

Create master order shipment tracking

Create shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

Update master order shipment tracking

Update shipment information like the parcels and the tracking information

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Enum: "shipmentParcel" "shipmentQuote"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": null,
  • "jsonapi": {
    },
  • "included": [
    ]
}

List Shipping Quotes

List multiple carrier service quotes that you can choose to ship your order. Please visit our FAQs for more information.'

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
Array of objects [ 1 .. 20 ]

Responses

Request samples

Content type
application/vnd.api+json
{
  • "parcels": [
    ]
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": [
    ]
}

Confirm Shipping Quote

Use this endpoint to confirm which quote you want to use to ship your order. You can confirm either custom or ankorstore quote.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
quote
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
labelFormat
string
Default: "default"
Enum: "full_page" "default"

This field is not required. If you don't' define it we will use the default label format as well.

object or object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "labelFormat": "default"
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Schedule Pickup for order

Use this endpoint for scheduling a pickup for the order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "pickupDate": "07-04-2022",
  • "pickupTime": "9-15",
  • "pickupAddress": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Fulfillment

ℹ️ Here you can find the information and endpoint specification related to fulfillment of the orders.

💡 About Fulfillment

Fulfillment is the process of preparing and shipping orders to customers via Ankorstore Fulfillment Centers. Brands that use fulfillment send their inventory to a warehouse in advance, and when orders come in, the warehouse picks, packs, and ships on the brand's behalf.

What does "fulfillable" mean?

The concept of a "fulfillable" is that which is required to prepare and ship a product (variant). While a Fulfillment Centre deals exclusively with items, which represents a single item that an employee can pick up and prepare for shipping. A fulfillable is simply a set of one or more items, that together represent a product as ordered.

Use the List Fulfillables endpoint to check stock availability for specific product variants before creating orders. For more detailed stock information — including quantities by location, status, and lot — use the Stock State endpoint from the Ankorstore Stock Tracking and Logistics API (ASTRAL).

Fulfillments

When a Master Order has fulfillment requested, one or more Fulfillments are created. Multiple fulfillments can be associated with a single master order (many-to-one). You can retrieve their details and track progress through the following statuses:

Status Description
requested Fulfillment has been requested for the order
created Fulfillment has been created in the warehouse system
scheduled Fulfillment is scheduled for picking
released Fulfillment has been released for picking
shipped Fulfillment has been shipped from the warehouse
cancelled Fulfillment has been cancelled
cancellation_requested A cancellation has been requested but not yet processed

Pass ?include=statusUpdates when retrieving a fulfillment to see the full history of status transitions.

Lots

If your products are lot-tracked or expiry-tracked, the List Lots endpoint shows the current lot inventory in the warehouse, including lot numbers, available quantities, and expiry/sell-by dates. You can filter and sort by available quantity, sell-by date range, and product name.

Fulfillment Costs

Use the Get Fulfillment Costs endpoint to estimate fulfillment costs before committing to an order. Provide the destination country, parcel dimensions, and picking quantity to receive a cost breakdown by category (shipping, pick fees by quantity tier).

⚠️ The cost estimation does not include packing consumables. The actual invoiced amount may differ.

Replenishments

Replenishments are required to send inventory to the warehouse. They follow a specific workflow:

Replenishment Workflow

stateDiagram-v2
    direction LR
    [*] --> created
    created --> confirmed : Brand confirms
    confirmed --> sent : Sent to warehouse
    sent --> delivered : Arrives at warehouse
    delivered --> received : Items put into stock
    received --> [*]
  • Created: When a replenishment is initially created, it will be at status created and is considered a draft. In this state, it can be edited via PATCH requests or deleted.
  • Confirmed: Once editing is complete, the status should be updated to confirmed as part of a PATCH request. At this point, the replenishment information will be sent to the warehouse (asynchronously).
  • Sent: Once the replenishment information is sent to the warehouse, the status changes to sent. The replenishment will remain in this status while waiting for delivery.
  • Delivered: When the replenishment physically arrives at the warehouse, its status will be automatically updated to delivered.
  • Received: Once the items are put into stock at the warehouse, the status will be updated to received. At this stage, receipts are added with the received stock quantities and lots.

Creating a Replenishment

Each replenishment requires a carrier name, shipment type, and a list of items with their fulfillment item IDs and quantities:

// POST /api/v1/fulfillment/replenishments
{
  "fulfillmentBrandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "warehouseId": "98765432-abcd-ef01-2345-678901234567",
  "shippingCarrierName": "DHL",
  "shipmentType": "PARCEL",            // "LTL", "FTL", or "PARCEL"
  "items": [
    {
      "fulfillmentItemId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "quantity": 100
    }
  ]
}

After creating a replenishment, update its status to confirmed via PATCH when you are ready to notify the warehouse.

How Fulfillment Connects to Orders

The diagram below shows how fulfillment fits into the order lifecycle:

graph LR
    A[Master Order] --> D[Fulfillment 1]
    A --> E[Fulfillment 2]
    F[Replenishment] --> G[Warehouse Stock]
    G --> D
    G --> E
  1. Brands send inventory to the warehouse via Replenishments
  2. When fulfillment is requested for a Master Order, one or more Fulfillments are created
  3. The warehouse picks items from stock and ships each fulfillment
  4. Use the fulfillment endpoints to track both your inventory and fulfillment status

Get Fulfillment Order

Returns details of a single fulfillment order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

Fulfillment order ID

query Parameters
include
string
Value: "statusUpdates"

A comma-separated list of resources to include (e.g: statusUpdates)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    },
  • "included": [
    ]
}

List Fulfillables

Returns a list of fulfillables with their stock availability

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
fulfillableIds[]
required
Array of strings <uuid> non-empty [ items <uuid > ]

A set of UUIDs representing the fulfillables to check availability for

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    },
  • "included": [
    ]
}

List lots in the warehouse

Returns a list of lots

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
page[limit]
integer
page[offset]
integer
sort
string
Enum: "availableQuantity" "expiryDate" "lotNumber" "sellByDate" "fulfillmentItems.productName" "-availableQuantity" "-expiryDate" "-lotNumber" "-sellByDate" "-fulfillmentItems.productName"

Specify what attribute(s) to sort by

filter[minAvailableQuantity]
integer

Request instances with a available quantity greater or equal to a given value

filter[minSellByDate]
string <datetime>

Request instances with a last sell by date greater or equal to a given value

filter[maxSellByDate]
string <datetime>

Request instances with a last sell by date smaller or equal to a given value

include
any

A comma-separated list of resources to include (e.g: fulfillmentItem)

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

Get the fulfillment costs

Returns a list of fulfillment costs for the given specification.

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required

The order fulfillment specification.

required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

List Brand Replenishments

Returns a list of declared replenishments

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
page[limit]
integer
page[offset]
integer
sort
string
Default: "-submittedAt"

Specify what attribute(s) to sort by

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

Create Replenishment

Creates a new replenishment

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
brandId
integer
Deprecated

deprecated, use fulfillmentBrandId instead

fulfillmentBrandId
string <uuid>
warehouseId
string <uuid>
shippingCarrierName
required
string
shipmentType
required
string
Enum: "" "LTL" "FTL" "PARCEL"
required
Array of objects (ReplenishmentItem)
id
string <uuid>

Responses

Request samples

Content type
application/vnd.api+json
{
  • "brandId": 0,
  • "fulfillmentBrandId": "190f203a-1767-4d67-a4ee-b3e306d130f8",
  • "warehouseId": "42912a8b-9d3f-4436-9cfe-fb2306e3310f",
  • "shippingCarrierName": "string",
  • "shipmentType": "",
  • "items": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Details of a single replenishment

Returns details of a single replenishment

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

Replenishment ID

header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Update a replenishment

Update a replenishment

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

Replenishment ID

header Parameters
Accept
string

application/vnd.api+json

Request Body schema: application/vnd.api+json
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "jsonapi": {
    }
}

Delete a draft replenishment

Delete a draft replenishment

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

Replenishment ID

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    }
}

OrderPay

ℹ️ This section describes the API endpoints for managing OrderPay orders and customers. OrderPay allows brands to create and manage orders for their own customers, handle payments, and track order lifecycle — all through the Ankorstore platform.

💡 General Concepts

  • OrderPay Order - An order created by a brand on behalf of one of its customers. Unlike Internal Orders (placed by retailers on the Ankorstore marketplace), OrderPay orders are initiated by the brand itself. This enables brands to sell to customers outside the marketplace while still leveraging Ankorstore's payment processing, invoicing, and optionally, fulfillment services.
  • OrderPay Customer - A customer entity managed by the brand. Each customer has billing and shipping addresses, contact details, and associated payment methods. Customers must be created before orders can be placed for them.
  • Custom Items - Additional charges on an order beyond product line items, such as shipping fees, excise duties, or eco-taxes.

💡 Working with Customers

Before creating an order, you need to register the customer. Use the customer endpoints to create and manage your customer base.

Creating a Customer

A customer requires at minimum: store name, email, first/last name, phone number, and both billing and shipping addresses.

// POST /api/v1/order-pay/order-pay-customer
{
  "data": {
    "type": "order-pay-customer",
    "attributes": {
      "storeName": "La Boutique Verte",
      "email": "contact@laboutiqueverte.fr",
      "firstName": "Marie",
      "lastName": "Dupont",
      "company": {
        "phoneNumber": "+33612345678",
        "vatNumber": "FR12345678901",
        "vatExemption": false
      },
      "billingAddress": {
        "street": "12 Rue de la Paix",
        "postalCode": "75002",
        "city": "Paris",
        "countryCode": "FR"
      },
      "shippingAddress": {
        "street": "12 Rue de la Paix",
        "postalCode": "75002",
        "city": "Paris",
        "countryCode": "FR"
      }
    }
  }
}

Listing and Filtering Customers

You can retrieve your customers with optional filters:

[GET] /api/v1/order-pay/order-pay-customer?filter[storeName]=boutique&sort=storeName

The response uses page-based pagination with page[number] and page[size] parameters.

Including Payment Methods

When retrieving a single customer, pass ?include=paymentMethods to see the customer's stored payment methods.

💡 Working with Orders

Order Lifecycle

An OrderPay order goes through the following statuses:

stateDiagram-v2
    [*] --> created
    created --> brand_confirmed : Brand confirms
    created --> cancelled : Brand cancels
    brand_confirmed --> payment_confirmed : Payment processed
    brand_confirmed --> cancelled : Brand cancels
    payment_confirmed --> waiting_shipping
    waiting_shipping --> shipped
    shipped --> received
    received --> invoiced
    invoiced --> brand_paid
    brand_paid --> [*]
    cancelled --> [*]
Status Description
created Order has been created but not yet confirmed by the brand
brand_confirmed Brand has confirmed the order, payment will be processed
payment_confirmed Payment has been successfully processed
waiting_shipping Order is awaiting shipment
shipped Order has been shipped
received Customer has received the order
invoiced Invoice has been generated
brand_paid Brand has been paid for the order
cancelled Order has been cancelled

Creating an Order

To create an order you need the customer UUID and at least one product line item. Each item requires a productVariantUuid, a quantity (in packs), and pricing in the brand's currency.

⚠️ The quantity field represents the number of packs, not individual units. For example, if a product variant is sold in packs of 6, a quantity of 2 means 12 individual units.

// POST /api/v1/order-pay/order-pay-orders
{
  "data": {
    "type": "order-pay-orders",
    "attributes": {
      "customerUuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "customReference": "SHOP-12345",  // Your reference, shown on customer invoice
      "items": [
        {
          "productVariantUuid": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "quantity": 2,
          "amounts": {
            "brandUnitPrice": 1500,       // 15.00 EUR in cents
            "discountRate": 10            // 10% discount
          }
        }
      ],
      "customItems": [
        {
          "type": "shippingFees",
          "amount": 800                   // 8.00 EUR in cents, excl. VAT
        }
      ],
      "shippingMethod": "custom"          // "custom" or "fulfillment"
    }
  }
}

Shipping Methods

Method Description
custom You ship the order using your own carrier
fulfillment The order is fulfilled via AnkorLogistics Fulfillment Centre

When using fulfillment, you can optionally provide delivery instructions:

  • deliverySchedule - Customer opening times with day-of-week and time slots
  • packingInstruction - Services like PALLETISE, CUSTOM_BUILD, or DOCS
  • deliveryAppointment - Whether an appointment is required for delivery

Custom Items

Use customItems to add charges beyond product line items:

Type Description
shippingFees Shipping charges
exciseDuties Excise duties (e.g., on alcohol)
ecoTax Environmental taxes

⚠️ The amounts.shippingFeesAmount field is deprecated. Use customItems with type shippingFees instead.

Custom Reference

Use the customReference field to link orders back to your own system (e.g., a Shopify order ID). This reference appears on the customer's invoice and can be up to 64 characters.

Confirming and Cancelling Orders

After creating an order, you can:

  • Confirm it via POST /api/v1/order-pay/order-pay-orders/{id}/-actions/confirm — this triggers payment processing
  • Cancel it via POST /api/v1/order-pay/order-pay-orders/{id}/-actions/cancel — with an optional reason

Including Payment Details

When retrieving an order, pass ?include=payment or ?include=payment.transactions to see payment status and transaction details.

💡 Amounts and Currencies

All monetary amounts are represented as integers in the lowest denomination of the currency (e.g., cents for EUR). Every order response includes both brand-currency and customer-currency amounts, with formatted string equivalents for display purposes.

For example, a line item response includes fields like:

  • brandUnitPrice: 1500 (integer, cents)
  • brandUnitPriceFormatted: "15.00 EUR" (string, for display)
  • customerUnitPrice: 1320 (integer, cents in customer currency)
  • customerUnitPriceFormatted: "13.20 GBP" (string, for display)

VAT is calculated automatically based on the customer's address and product configuration.

List customers

Retrieves a list of customers associated with an OrderPay account. The result is paginated. Furthermore a filter can be applied on the result.

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
filter[storeName]
string
filter[email]
string
page[number]
integer
Default: 1

Page number, starting at 1

page[size]
integer
Default: 20

Maximum number of elements per page

sort
string
Enum: "id" "storeName"

Comma-separated list of attributes to sort by (storeName by default)

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": [
    ],
  • "meta": {
    }
}

Create a customer

Creates a new OrderPay customer.

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Retrieve a single customer

Retrieves details for a single customer.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order_pay_customer
required
string <uuid>

Customer ID

query Parameters
include
string
Value: "paymentMethods"

A comma-separated list of resources to include

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Update a customer profile

Updates a customer profile.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order_pay_customer
required
string <uuid>

Customer ID

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Create a new order

Creates a new OrderPay order.

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Retrieve an order

Retrieves an OrderPay order by ID.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

UUID of the requested resource

query Parameters
include
string
Examples: include=payment include=payment.transactions

Include related resources in the response

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Update an order

Updates an existing OrderPay order.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

UUID of the requested resource

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Cancel an order

Allows brand to cancel an order

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

UUID of the requested resource

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
optional
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Confirm an order

Allows brand to confirm order.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

UUID of the requested resource

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    },
  • "included": [
    ]
}

Webhooks

ℹ️ This section describes the API endpoints which can be used for managing webhook subscriptions.

💡 Overview

In order to be able to manage Webhook Subscriptions via API you should understand the relationship model around webhook notifications system. In general, a Webhook Subscription always contains a list of chosen events and always belongs to an application. More on this later.

Application

Application is a representation of a single private integration. Whenever you create a new set of credentials for accessing API in your account, under the hood you create an Application entity. Once created, the entity allows you to attach as many Webhook Subscriptions as needed. It means, there's no way to manage Webhook Subscriptions outside of Application context and this restriction is also reflected in the current API architecture.

Webhook Subscription

Webhook Subscription is an entity representing "an intent of receiving HTTP requests to the specified URL whenever one of the chosen Webhook Subscription Events is triggered on the platform". For every new URL you should create a separate Webhook Subscription.

Webhook Subscription Events

Webhook Subscription Event is a name of the corresponding event fired on certain conditions on the platform. There are a list of only valid and supported events which can be used in the Webhook Subscription management. You can fetch this list using a corresponding endpoint

💡 How to create a new webhook subscription?

1. Find ApplicationID

As it was mentioned above, Webhook Subscription always belong to some application. Hence, you should start from finding out the ID of the target Application in order to link the new Webhook Subscription to it. For this purpose you should use List Applications endpoint. This endpoint returns a list of all available Applications in your account, so you could identify the needed one by name, developerEmail or clientId in the Application resource body:

GET https://ankorstore.com/api/v1/applications

{
  "data": {
    "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
    "type": "application",
    "attributes": {
      "name": "My Application",
      "developerEmail": "dev@acme.com",
      "clientId": "k322k7frs87e8w7hri3jkke7ry7",
      "clientSecret": null
    }
  }
}

NOTE: The client secret in the response is always null due to security reasons. The actual client secret can be seen only via UI and only once - during the creation of the application.

2. Find valid webhook events to subscribe to

Next step should be to find the valid names of the webhook events which you could use in the create webhook request payload:

GET https://ankorstore.com/api/v1/webhook-subscriptions/events

{
  "data": [
    {
      "type": "webhook-subscriptions/events",
      "id": "order.brand_created"
    },
    {
      "type": "webhook-subscriptions/events",
      "id": "order.brand_accepted"
    }
  ]
}

You can find detailed description of each event in the dedicated section of the docs.

3. Create webhook subscription

Now you are all set for creating actual webhook subscription. The prerequisites for this step are:

  • The Application ID from step 1 (43efbfbd-bfbd-1eef-1e6a-6200efbfbdef in this example)
  • The chosen events from step 2 (e.g. order.brand_created and order.brand_accepted) With this setup the final request should look like:

POST https://ankorstore.com/api/v1/webhook-subscriptions

{
  "data": {
    "type": "webhook-subscriptions",
    "attributes": {
      "url": "https://my-app.com/webhook-listener",
      "events": [
        "order.brand_created",
        "order.brand_accepted"
      ]
    },
    "relationships": {
      "application": {
        "data": {
          "type": "applications",
          "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef"
        }
      }
    }
  }
}

After this request is succeeded, you will start receiving notification about chosen events on the chosen URL.

💡 How to manage existing Webhook Subscriptions?

For most of the operations with an existing Webhook Subscription you need to fetch its ID first. It can be achieved by using List Applications endpoint and explicit including the Webhook Subscription resource into the response.

GET /api/v1/applications?include=webhookSubscriptions

{
  "data": {
    "id": "`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
    "type": "applications",
    "attributes": {},
    "relationships": {
      "webhookSubscriptions": {
        "data": [
          {
            "type": "webhook-subscriptions",
            "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606"
          }
        ]
      }
    }
  },
  "includes": [
    {
      "type": "webhook-subscriptions",
      "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606",
      "attributes": {
        "url": "https://my-app.com/webhook-listener",
        "events": [
          "order.brand_created",
          "order.brand_accepted"
        ],
        "signingSecret": "LQxZs6kiSyNr45hjT32OsntYddzH4BvToLIQcgSL"
      }
    }
  ]
}

The data in this response gives you an idea about the current Webhook Subscription state and also lets you update or delete Webhook Subscriptions, whenever needed. For updating or deleting Webhook Subscription you need to use the Webhook Subscription ID received in the response (a863e15d-3d20-4af2-b92b-d9590a4a9606 in this particular case). Please refer to the Update webhook subscription and Delete webhook subscription endpoints for detailed information.

List Applications

List existing application for the current authenticated user

Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    },
  • "included": [
    ],
  • "jsonapi": {
    }
}

List Webhook Subscription Events

Returns a list of webhook events available in the system

Authorizations:
ProductionOAuth2ClientCredentials

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ]
}

Add Webhook Subscription to Application

Adds a new webhook subscription to the existing application

Authorizations:
ProductionOAuth2ClientCredentials
Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

Update Application Webhook Subscription

Update application subscription with given ID

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
webhookSubscriptionId
required
string

Webhook Subscription ID

header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    ],
  • "jsonapi": {
    }
}

Delete Application Webhook Subscription

Delete application webhook subscription by given ID

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
webhookSubscriptionId
required
string

Webhook Subscription ID

header Parameters
Accept
required
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "errors": [
    ]
}

Testing

ℹ️ This section is dedicated to the testing API during development process. The listed endpoints are not available on production environment.

Creating Test Orders

When using the public sandbox, a subsection of the API will be available to create test orders.

This endpoint /api/testing/orders/create can be called to create a new test order with a new retailer, and a couple of new products.

You can also pass in options to specify the exact retailer or products themselves. To find out more, you can view the endpoint specification here.

Finding the Retailer ID

There is an option to specify the retailerId to use the same retailer for every test order, to find this, login as that retailer you created and open up the developer tools. You will see it logged to the console.

Create Test Order

Creates a test order ready to be confirmed based on the options provided. ONLY AVAILABLE IN SANDBOX ENVIRONMENT.

Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
include
header Parameters
Accept
string

application/vnd.api+json

Content-Type
string

application/vnd.api+json

Request Body schema: application/vnd.api+json

The options that can be provided when creating a test order

retailerId
string or null

The Retailer Id

itemQuantity
integer or null [ 1 .. 999 ]

If productVariants/productOptions are not provided, then this will set the quantity each order item created.

Array of objects or null unique

List of variant IDs and their quantities. Cannot be included with productOptions.

Array of objects or null unique

List of option IDs and their quantities - Only use if you are currently using the old options system. Cannot be included with productVariants

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "retailerId": "5ee4d438-0489-4634-aa60-746f485af458"
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Deprecated

ℹ️ Here you can find the endpoints which are currently deprecated and will be removed in the future versions of the API. We strongly encourage you to migrate away from these endpoints in order to prevent any future problems with API.

❄️ Shipping an Order

⚡ This documentation is deprecated

Schedule a Pickup

If the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup for this order. A pickup can only be scheduled on a working day (monday to friday). For full information please refer to the API documentation.

Pickup is not accepted

For now, Ankorstore does not know in advance which date/time configuration is available, if the requested pickup is denied please try a different date or time frame.

[Ordering] Accept Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

[Ordering] Reject Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "order": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}

Ship Order With Custom

[Deprecated] This endpoint is deprecated. We encourage you to use the List Order Quotes endpoint instead.

Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

Request Body schema: application/vnd.api+json
required
object

Responses

Request samples

Content type
application/vnd.api+json
{
  • "shipping": {
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    },
  • "data": {
    }
}